{"record":{"id":"38cc7145b3b5298d","repo":"zylon-ai/private-gpt","slug":"server-did-not-become-ready-within-health-timeou","errorCode":null,"errorMessage":"Server did not become ready within {_HEALTH_TIMEOUT}s","messagePattern":"Server did not become ready within (.+?)s","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"private_gpt/cli/commands/run.py","lineNumber":318,"sourceCode":"\n    binary = _APP_BINARIES.get(app_name, app_name)\n    resolved = shutil.which(binary)\n    if resolved is None:\n        typer.echo(f\"Binary not found in PATH: {binary!r}\", err=True)\n        raise SystemExit(1)\n\n    base_url = _base_url()\n    server_proc: subprocess.Popen[bytes] | None = None\n\n    if not no_server and not _is_server_up(base_url):\n        typer.echo(\"Server not reachable, starting automatically...\")\n        server_proc = _start_server_subprocess()\n        if not _wait_for_server(base_url):\n            server_proc.terminate()\n            typer.echo(\n                f\"Server did not become ready within {_HEALTH_TIMEOUT}s\", err=True\n            )\n            raise SystemExit(1)\n        typer.echo(\"Server is ready.\")\n\n    match app_name:\n        case \"opencode\":\n            _inject_opencode_env(model)\n        case _:\n            inject_app_env(_pick_model(model))\n\n    cmd: list[str] = [resolved]\n    if session:\n        cmd += [\"--resume\", session]\n    if auto_approve:\n        cmd.append(\"--yes\")\n    cmd += extra_args\n\n    if detach:\n        run_id = uuid.uuid4().hex[:8]\n        log_dir = Path.home() / \".private-gpt\" / \"runs\"","sourceCodeStart":300,"sourceCodeEnd":336,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/cli/commands/run.py#L300-L336","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Start the server manually with `private-gpt serve` and read its logs — the real startup error appears there.","Fix the underlying dependency (start ollama/postgres, verify settings profiles) and retry `private-gpt run`.","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.","Free the configured port (lsof -i :8000) if another process holds it.","As a workaround, run against an already-running server: `private-gpt run <app> --no-server`."],"exampleFix":"// before\n$ private-gpt run claude-code\nServer not reachable, starting automatically...\nServer did not become ready within 30s\n\n// after\n$ private-gpt serve   # watch logs, fix the failing component\n$ private-gpt run claude-code","handlingStrategy":"fallback","validationCode":"import urllib.request, json\n\ndef server_up(base_url: str) -> bool:\n    try:\n        with urllib.request.urlopen(f\"{base_url}/health\", timeout=2) as r:\n            return r.status == 200\n    except Exception:\n        return False\n\nif not server_up(base_url):\n    # start `private-gpt serve` manually and read its logs","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Warm the server once with `private-gpt serve` before using `run`.","Keep ollama/pgvector/dependencies running so boot is fast.","Watch serve logs for the real startup error instead of retrying `run`.","Use --no-server against an already-running instance."],"tags":["cli","server","startup","timeout","health-check"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}