zylon-ai/private-gpt · error

Server did not become ready within {_HEALTH_TIMEOUT}s

Error message

Server did not become ready within {_HEALTH_TIMEOUT}s

What it means

CLI error from `private-gpt run <app>` when auto-starting the HTTP server. If the server is not reachable, run.py launches it as a subprocess (_start_server_subprocess) and polls health via _wait_for_server; if it is still not healthy after _HEALTH_TIMEOUT seconds, it terminates the subprocess, prints this message to stderr, and exits 1.

Source

Thrown at private_gpt/cli/commands/run.py:318

    binary = _APP_BINARIES.get(app_name, app_name)
    resolved = shutil.which(binary)
    if resolved is None:
        typer.echo(f"Binary not found in PATH: {binary!r}", err=True)
        raise SystemExit(1)

    base_url = _base_url()
    server_proc: subprocess.Popen[bytes] | None = None

    if not no_server and not _is_server_up(base_url):
        typer.echo("Server not reachable, starting automatically...")
        server_proc = _start_server_subprocess()
        if not _wait_for_server(base_url):
            server_proc.terminate()
            typer.echo(
                f"Server did not become ready within {_HEALTH_TIMEOUT}s", err=True
            )
            raise SystemExit(1)
        typer.echo("Server is ready.")

    match app_name:
        case "opencode":
            _inject_opencode_env(model)
        case _:
            inject_app_env(_pick_model(model))

    cmd: list[str] = [resolved]
    if session:
        cmd += ["--resume", session]
    if auto_approve:
        cmd.append("--yes")
    cmd += extra_args

    if detach:
        run_id = uuid.uuid4().hex[:8]
        log_dir = Path.home() / ".private-gpt" / "runs"

View on GitHub (pinned to 4a030776a3)

Solutions

1. Start the server manually with `private-gpt serve` and read its logs — the real startup error appears there.
2. Fix the underlying dependency (start ollama/postgres, verify settings profiles) and retry `private-gpt run`.
3. If the machine is just slow (model download), let `private-gpt serve` finish booting once, then `private-gpt run <app>` will detect the healthy server and skip auto-start.
4. Free the configured port (lsof -i :8000) if another process holds it.
5. As a workaround, run against an already-running server: `private-gpt run <app> --no-server`.

Example fix

// before
$ private-gpt run claude-code
Server not reachable, starting automatically...
Server did not become ready within 30s

// after
$ private-gpt serve   # watch logs, fix the failing component
$ private-gpt run claude-code

import urllib.request, json

def server_up(base_url: str) -> bool:
    try:
        with urllib.request.urlopen(f"{base_url}/health", timeout=2) as r:
            return r.status == 200
    except Exception:
        return False

if not server_up(base_url):
    # start `private-gpt serve` manually and read its logs

When it happens

Trigger: Server startup hangs due to model downloading at boot, missing dependencies (vector store, embedding backend) that crash the child process, a port conflict on the configured port, or a cold start slower than the health timeout. Also when the profile settings make startup fail (bad pgvector/ollama URL).

Common situations: First run downloading large models; Docker resource limits slowing boot; ollama/pgvector not running so initialization blocks; port already occupied by another service; slow disk/CPU where boot exceeds the timeout.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Server is already running with PID {existing_pid}
• Binary not found in PATH: {binary!r}
• Unknown command: {cmd!r}
• OVERLOADED_CONDENSATION_ERROR
• Default LLM model '{model_id}' could not be initialized: {e}

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/38cc7145b3b5298d. Report an issue: GitHub.