t8y2/dbx · error · TimeoutError

IoTDB is not reachable at {host}:{port}

Error message

IoTDB is not reachable at {host}:{port}

What it means

wait_for_server() polls a TCP connection to the IoTDB server for a bounded period (retries every 0.5s with 1s connect timeouts). If the server never accepts a connection before the deadline it raises TimeoutError naming the host:port. This is a startup-readiness guard for the benchmark harness.

Source

Thrown at agents/drivers/iotdb/bench/run.py:103

        ["go", "build", "-o", str(GO_BINARY), "."],
        cwd=BENCH_DIR / "go",
        check=True,
        stdout=sys.stderr,
        stderr=sys.stderr,
    )


def wait_for_server(environment: dict[str, str]) -> None:
    host = environment.get("IOTDB_HOST", "127.0.0.1")
    port = int(environment.get("IOTDB_PORT", "6667"))
    deadline = time.monotonic() + env_float("BENCH_SERVER_TIMEOUT", 60.0)
    while time.monotonic() < deadline:
        try:
            with socket.create_connection((host, port), timeout=1):
                return
        except OSError:
            time.sleep(0.5)
    raise TimeoutError(f"IoTDB is not reachable at {host}:{port}")


def run_json(command: list[str], environment: dict[str, str]) -> dict:
    completed = subprocess.run(
        command,
        env=environment,
        text=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        check=False,
        timeout=env_float("BENCH_COMMAND_TIMEOUT", 180.0),
    )
    if completed.returncode != 0:
        raise RuntimeError(
            f"command failed ({' '.join(command)}):\nstdout:\n{completed.stdout}\nstderr:\n{completed.stderr}"
        )
    for line in reversed(completed.stdout.splitlines()):
        try:

View on GitHub (pinned to c0390bff16)

Solutions

1. Start the IoTDB server and confirm it listens: ss -ltnp | grep <port>
2. Verify host/port env vars match the server's actual bind address
3. Test connectivity manually: python -c "import socket;socket.create_connection(('host',port),timeout=2)"
4. Increase the wait deadline in main()/wait_for_server if startup is legitimately slow
5. Check firewall/security-group rules if the server runs on another host

Example fix

// before
$ python run.py   # TimeoutError: IoTDB is not reachable at localhost:6667
// after
$ docker compose up -d iotdb && python run.py   # or fix BENCH_IOTDB_PORT=6667

import socket

def server_is_up(host, port, timeout=2.0):
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True
    except OSError:
        return False

assert server_is_up(host, port), f"start IoTDB at {host}:{port} first"

try:
    wait_for_server(host, port)
except TimeoutError:
    sys.exit(f"IoTDB unreachable at {host}:{port}; start it or fix host/port")

When it happens

Trigger: IoTDB is not started, listens on a different host/port than the benchmark's env config, is still initializing past the deadline, or a firewall/network policy blocks the port — every socket.create_connection attempt raises OSError until time runs out.

Common situations: Forgetting to start the IoTDB container before running bench/run.py; wrong BENCH host/port env; slow first-time startup (WAL replay) exceeding the wait window; Docker network misconfiguration.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• ZooKeeper connection timed out before a session was establis
• ETCD_HISTORY_TIMEOUT
• ZooKeeper connection timed out before a session was establis
• ZooKeeper session expired during connection
• xugu operation timed out

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/1ca72797a91ae7f6. Report an issue: GitHub.