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"#

pip install dir not on PATH. Two options:

# call the module directly
python3 -m openprogram <args>

# or add the user-base bin to PATH (idempotent)
echo 'export PATH="$(python3 -m site --user-base)/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 install (multi-repo)#

For working on GUI-Agent-Harness / Research-Agent-Harness side-by-side with OpenProgram:

pip install -e "$OPENPROGRAM_DIR"                   # always first
pip install -e "$GUI_HARNESS_DIR"                   # depends on openprogram
pip install -e "$RESEARCH_HARNESS_DIR"

openprogram/functions/agentics/{GUI,Research}-Agent-Harness are symlinks — recreate if a repo moves:

cd openprogram/functions/agentics
rm -f GUI-Agent-Harness  && ln -s "$GUI_HARNESS_DIR"      GUI-Agent-Harness
rm -f Research-Agent-Harness && ln -s "$RESEARCH_HARNESS_DIR" Research-Agent-Harness

pip install -e writes absolute paths — rerun it from the new location if you rename a parent folder.

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. openprogram rescue goes beyond diagnosis and prints the fix commands directly. Read their output before raising an issue.

import openprogram raises ModuleNotFoundError#

The package isn't installed in the active Python. Either run the installer (clone OpenProgram + ./scripts/install.sh) or activate the venv where it is installed.

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.