Troubleshooting#

Common gotchas. The full operator runbook for a fresh install / upgrade is in GETTING_STARTED.md; this page collects the recurring "it doesn't work" cases.

"No provider available"#

openprogram providers lists the credentials on file; openprogram providers discover scans for external CLI logins (Claude Code, Codex, Gemini CLI) to adopt. Common causes:

• forgot openprogram providers login <provider> (or the login of the matching external CLI)
• API key set in a different shell than the one running the worker
• token expired — log in again; openprogram providers doctor diagnoses credential expiry / refresh / conflicts

"command not found: openprogram"#

The supported CLI/server installer creates ~/.local/bin/openprogram. Run the installer again, then ensure that directory is on PATH:

curl -fsSL https://openprogram.io/install | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Web UI port in use#

Set this env var before starting the worker (one port serves API, WebSocket, and web UI):

export OPENPROGRAM_WEB_PORT=8101         # single port (defaults to 18100)

Or persist the preference: openprogram ports --port 8101.

Local development#

Source-checkout development uses uv sync --locked --extra dev. External harness development is documented in Installing harnesses and is not a normal product installation path.

Worker doesn't start / starts on the wrong port#

openprogram doctor runs a fast end-to-end check: the Python/Node/git toolchain, skills and plugins loading, provider credentials, MCP servers, disk cache, and whether the worker is listening on :18100. On Windows it also reports long-path configuration and a read-only Defender performance advisory. It never changes the registry, Defender exclusions, or file ACLs. openprogram rescue goes beyond diagnosis and prints the fix commands directly. Read their output before raising an issue.

import openprogram raises ModuleNotFoundError#

Managed product installations use a private bundled Python and intentionally do not expose OpenProgram to whichever Python is active in your shell. For source development, run uv sync --locked in the checkout, then execute scripts with uv run --project /path/to/OpenProgram python ...; alternatively, activate the checkout's .venv first.

CI says "tests pass" but Mac runs differently#

A handful of tests are explicitly skipped on bare CI runners because they need a configured provider in $HOME. The skip list lives in the test files themselves — search for pytest.mark.skipif. Dev machines with credentials see the full suite.