Skip to content

troubleshooting.md

Latest commit

 

History

History
83 lines (59 loc) · 2.95 KB

troubleshooting.md

File metadata and controls

83 lines (59 loc) · 2.95 KB
Raw

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 one of these env vars before starting the worker:

export OPENPROGRAM_WEB_PORT=8101         # frontend (defaults to 18100)
export OPENPROGRAM_BACKEND_PORT=8102     # FastAPI (defaults to 18109)

Or persist the preference: openprogram ports --backend 8102 --frontend 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 :18109. 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.