zylon-ai/private-gpt · error

Binary not found in PATH: {binary!r}

Error message

Binary not found in PATH: {binary!r}

What it means

CLI error from `private-gpt run <app>` (private_gpt/cli/commands/run.py). The command resolves the app binary — a known name from _APP_BINARIES or the literal argument — via shutil.which; if the executable is not on PATH, it prints 'Binary not found in PATH: <name>' to stderr and exits with code 1 before starting any server.

Source

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

        False, "--auto-approve", help="Skip confirmations (CI mode)"
    ),
    no_server: bool = typer.Option(
        False, "--no-server", help="Skip server detection and auto-start entirely"
    ),
) -> None:
    """Launch a connected app (claude-code, openclaw, custom).

    Pass extra arguments to the app after --:

        private-gpt run claude-code -- --resume abc123
    """
    extra_args: list[str] = ctx.args

    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)

View on GitHub (pinned to 4a030776a3)

Solutions

1. Install the target CLI (e.g. `npm install -g @anthropic-ai/claude-code` for claude-code) and confirm with `which <binary>`.
2. If the binary exists but is not found, fix PATH (export PATH="$HOME/.local/bin:$PATH") or use an absolute path as the app name.
3. For custom apps, pass the exact executable name: `private-gpt run ./node_modules/.bin/mytool`.
4. Verify the server side separately with `private-gpt run <app> --no-server` once the binary resolves.

Example fix

// before
$ private-gpt run claude-code
Binary not found in PATH: 'claude-code'

// after
$ npm install -g @anthropic-ai/claude-code
$ which claude-code && private-gpt run claude-code

import shutil, sys

binary = "claude-code"  # target app binary
if shutil.which(binary) is None:
    sys.exit(f"Install {binary} first; not found in PATH")

When it happens

Trigger: Running `private-gpt run claude-code` without the claude-code CLI installed/on PATH; `private-gpt run opencode` without opencode installed; `private-gpt run my-custom-tool` where my-custom-tool is neither in _APP_BINARIES nor an executable on PATH.

Common situations: New machine or container without the companion CLI installed; nvm/pyenv/conda environments that shadow PATH; running inside Docker where the app image only contains private-gpt; typos in the custom binary name.

Related errors

• Server is already running with PID {existing_pid}
• Unknown command: {cmd!r}
• Server did not become ready within {_HEALTH_TIMEOUT}s
• The arq worker mode does not support arguments yet

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