Sign up

Connection Failures — TerminusDB Troubleshooting

Open inAnthropic

Connection Failures

This page covers errors you encounter when your client cannot reach the TerminusDB server — the server is not running, the port is wrong, Docker networking is misconfigured, the browser blocks the request due to CORS, or the connection times out.

Symptoms

  • ECONNREFUSED or Connection refused in your terminal
  • fetch failed or NetworkError in the browser console
  • CORS policy: No 'Access-Control-Allow-Origin' header error in the browser
  • Request hangs indefinitely and eventually times out
  • getaddrinfo ENOTFOUND when using a hostname

Common causes

Server not running

Error message: connect ECONNREFUSED 127.0.0.1:6363

Cause: TerminusDB is not started, or the Docker container has exited.

Fix:

  1. Check if the container is running:
    Example: Bash
    docker ps | grep terminusdb
  2. If nothing appears, start the container:
    Example: Bash
    docker start terminusdb
  3. If the container does not exist, create it:
    Example: Bash
    docker run -d --name terminusdb \
  -p 6363:6363 \
  -v terminusdb_storage:/app/terminusdb/storage \
  terminusdb/terminusdb-server

Wrong port or host

Error message: connect ECONNREFUSED 127.0.0.1:6364 (or any non-6363 port)

Cause: Your client is pointing to a port that TerminusDB is not listening on, or you are using localhost when the server is on a different host.

Fix:

  1. Confirm the port mapping:
    Example: Bash
    docker port terminusdb
    You should see 6363/tcp -> 0.0.0.0:6363.
  2. Update your client connection URL to match the mapped port.
  3. If running inside another container, use the container name or Docker network IP — not localhost.

Docker networking (container-to-container)

Error message: getaddrinfo ENOTFOUND localhost or ECONNREFUSED from within another container

Cause: When two containers need to communicate, localhost inside a container refers to that container itself, not the host machine.

Fix:

  1. Put both containers on the same Docker network:
    Example: Bash
    docker network create terminusdb-net
docker network connect terminusdb-net terminusdb
docker network connect terminusdb-net your-app
  2. Use the container name as the hostname:
    Example: Text
    http://terminusdb:6363
  3. Alternatively, on Docker Desktop, use host.docker.internal to reach the host:
    Example: Text
    http://host.docker.internal:6363

CORS errors from the browser

Error message: Access to fetch at 'http://localhost:6363' from origin 'http://localhost:3000' has been blocked by CORS policy

Cause: TerminusDB unconditionally allows all cross-origin requests — it reflects back whatever Origin header is sent. If you are seeing a genuine CORS error, the most common causes are: a browser extension blocking requests, a proxy stripping CORS headers, or connecting to a different host than you think (e.g., the wrong port).

Fix:

  1. Confirm TerminusDB is actually running and reachable at the expected URL:
    curl -s http://localhost:6363/api/ok
    You should see "ok". If not, the server is not running — see Server not running above.
  2. Check your browser's network tab for the actual request URL and response headers. If Access-Control-Allow-Origin is missing, the request never reached TerminusDB (firewall, proxy, or wrong URL).
  3. There is no TERMINUSDB_CORS environment variable — do not set one. See Calling TerminusDB from the Browser for a working fetch example.

Connection timeout

Error message: timeout of 5000ms exceeded or request hangs with no response

Cause: A firewall, VPN, or misconfigured network is preventing packets from reaching the server. The server may also be under heavy load.

Fix:

  1. Verify basic connectivity:
    curl -s -o /dev/null -w "%{http_code}" http://localhost:6363/api/info
    A healthy server returns 200.
  2. Check firewall rules are not blocking port 6363.
  3. If behind a corporate VPN, ensure local traffic is not being routed through the tunnel.
  4. Increase the client timeout as a temporary workaround:
    Example: JavaScript
    const client = new TerminusClient.WOQLClient("http://localhost:6363", {
  user: "admin",
  key: "root",
})

Still stuck?

Open inAnthropic
Report issue

Was this helpful?