Skip to main content

​
First Step: Run Doctor

Before diving into specific errors, run the built-in diagnostic: 
orch doctor
This checks your environment, configuration, connectivity, authentication, and LLM setup. Most issues are caught here with actionable fix suggestions. Add --verbose to see detailed information about each check: 
orch doctor --verbose
The verbose mode shows configuration paths, environment variable values, and detailed status for each LLM provider — essential when debugging setup issues.

​
Authentication & Login

​
”Not logged in. Run orchagent login first.”

You’re running a command that requires authentication but no API key is configured. Fix: 
# Interactive login (opens browser)
orch login

# Non-interactive (CI/CD)
orch login --key sk_live_xxx

# Or set the environment variable
export ORCHAGENT_API_KEY=sk_live_xxx

​
“Authentication failed” (exit code 2)

Your API key is invalid, expired, or revoked. Causes:
  • Key was deleted from the dashboard
  • Key was revoked via orch logout
  • Key is from a different environment (staging vs production)
Fix: 
orch logout
orch login

​
“Access denied” (403)

Your API key doesn’t have permission for this operation. Common causes:
  • Accessing a private agent you don’t own
  • Operating on a workspace you’re not a member of
  • Using an API key without the required scope
Fix:
  • Check you’re using the right workspace: orch workspace list
  • Check you have access to the agent: orch info org/agent
  • For workspace-scoped operations with --workspace, use browser login (orch login without --key)

​
Login hangs or times out

The browser auth flow uses a local callback server. If it hangs:
  1. Check your firewall isn’t blocking localhost ports
  2. Try a specific port: orch login --port 8910
  3. Fall back to key-based login: orch login --key sk_live_xxx
  4. Get a key from Settings > API Keys

​
Running Agents

​
”Agent not found” (404)

The agent doesn’t exist or you used the wrong reference format. Fix:
  • Use the full org/agent format: orch run acme/my-agent
  • Check spelling: orch info acme/my-agent
  • Check the version exists: orch info acme/my-agent@v2
  • If using a workspace, ensure the agent is published there: orch agents

​
”Invalid agent reference”

The agent reference format is wrong. Valid formats: 
orch run my-agent           # Uses your default org
orch run acme/my-agent      # Explicit org
orch run acme/my-agent@v2   # Specific version
Invalid formats: 
orch run acme/my-agent/v2   # Too many segments (use @ for version)

​
“No LLM key found” / LLM_KEY_REQUIRED

The agent needs an LLM provider key but none is available. For cloud runs (default): Add your key in Settings > LLM Keys, or pass inline: 
orch run acme/agent --key sk-... --provider openai
For local runs (--local): Set the environment variable for your provider: 
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...
# or
export GEMINI_API_KEY=...

​
“Agent exited with code X (no output)”

The agent process terminated without producing output. Common causes:
  • Missing dependency in requirements.txt
  • Python syntax error
  • Unhandled exception before any output was written
Debug steps:
  1. Run with verbose to see sandbox output: 
    orch run acme/my-agent --verbose --data '{}'
  2. Test locally: 
    echo '{}' | python main.py
  3. Check logs in the dashboard or via CLI: 
    orch logs

​
SANDBOX_ERROR (code_error)

Your agent code crashed during execution. The error output is from your code, not the platform. Fix:
  1. Read the error message — it’s your agent’s stderr (truncated to 500 chars)
  2. Check for missing dependencies in requirements.txt
  3. Test locally: orch run --local acme/my-agent --data '{}'
  4. Check full logs: orch logs <run-id>

​
SANDBOX_ERROR (setup_error)

The sandbox failed during setup, before your code ran. Common causes:
  • pip install failed for a dependency
  • Incompatible package versions
  • Package requires system libraries not in the sandbox
Fix:
  1. Verify requirements.txt installs cleanly: pip install -r requirements.txt
  2. Pin specific versions to avoid conflicts
  3. For system dependencies, use a custom environment

​
SANDBOX_TIMEOUT

The agent didn’t finish within its timeout limit. Fix:
  • Simplify the input or reduce the dataset
  • Increase the timeout in orchagent.json: 
    { "timeout_seconds": 120 }
  • Check if you’re on the Free tier (30s tool / 2 min agent limit) — upgrade for longer timeouts
  • For orchestrators, check if a sub-agent is slow: orch dag <run-id>

​
”This agent is server-only and cannot be downloaded” (DOWNLOAD_DISABLED)

The agent author has disabled local execution to protect their code. Fix: Run on the cloud (the default): 
orch run acme/agent --data '{}'
Remove the --local flag if you were using it.

​
”Rate limit exceeded” (429)

You’ve hit a platform rate limit. Fix:
  • Wait and retry — the error includes a suggested_wait_time
  • Check your usage: orch billing balance
  • Upgrade your plan for higher limits
  • See Rate Limits for per-tier limits

​
LLM_RATE_LIMITED

Your LLM provider (OpenAI, Anthropic, Gemini) is rate-limiting your API key. This is not an orchagent limit. Fix:
  • Wait and retry
  • Switch providers: orch run acme/agent --provider gemini
  • Check your provider dashboard for usage limits
  • The error message shows which alternative providers the agent supports

​
”Budget limit reached” (BUDGET_EXCEEDED)

Your workspace hard budget limit has been reached for the current billing window. Fix:
  • Wait for the budget window to reset
  • Increase the budget in Settings > Billing
  • Check usage: orch billing balance

​
JSON Input Errors

​
”Invalid JSON in —data option”

Shell special characters are breaking your JSON. Fix — use single quotes (Bash/Zsh): 
orch run acme/agent --data '{"text": "hello"}'
Fix — use a file instead: 
echo '{"text": "hello"}' > input.json
orch run acme/agent --data @input.json
Fix — use stdin: 
echo '{"text": "hello"}' | orch run acme/agent --data @-
PowerShell fix: 
orch run acme/agent --data "{\"text\": \"hello\"}"

​
“Missing required field”

The agent’s input schema requires a field you didn’t provide. Fix:
  1. Check the schema: orch schema acme/agent (or orch info acme/agent)
  2. Provide all required fields in your --data JSON

​
Publishing

​
”No orchagent.json found”

You’re running orch publish outside an agent directory. Fix:
  • cd into your agent directory first
  • Or create a new agent: orch init my-agent

​
”No prompt.md found”

Prompt-based and managed-loop agents need a prompt.md file. Fix: Create prompt.md in your agent directory with your prompt template. The "prompt" field in orchagent.json is not used — the CLI reads prompt.md.

​
Agent name validation errors

Agent names must follow these rules:
  • 2-50 characters
  • Lowercase only
  • Letters, numbers, and hyphens only
  • Must start and end with a letter or number
  • No consecutive hyphens
# Good
orch init my-agent
orch init code-reviewer-2

# Bad
orch init My-Agent        # uppercase
orch init a               # too short
orch init my--agent       # consecutive hyphens

​
”runtime.command and loop cannot both be set”

Your orchagent.json has both runtime.command (code runtime) and loop (managed loop) configured. These are mutually exclusive execution modes. Fix: Remove one:
  • Keep runtime.command if your code handles everything (tool-type)
  • Keep loop if you want the platform-managed LLM tool-use loop (agent-type)

​
“Unpublished dependencies”

Your agent’s manifest references other agents that haven’t been published yet. Fix: Publish dependencies first (leaf-first order), or use batch publish: 
# From parent directory containing all agents
orch publish --all
This automatically resolves dependency order.

​
”Publish blocked by security scan” (SECURITY_BLOCKED)

The security scanner detected dangerous patterns in your skill content (shell injection, data exfiltration, etc.). Fix: Review the detected patterns listed in the error output. If they’re false positives, restructure your skill content to avoid the flagged patterns.

​
Schema mismatch warning

Your prompt.md template variables don’t match your schema.json fields. Fix: Ensure every {{variable}} in prompt.md has a corresponding field in schema.json, and vice versa.

​
Workspaces

​
”No workspace specified”

A command that requires workspace context doesn’t know which workspace to use. Fix: 
# Set a default workspace
orch workspace use my-team

# Or pass it per-command
orch logs --workspace my-team
orch secrets list --workspace my-team

​
“Workspace not found”

The workspace slug doesn’t match any workspace you have access to. Fix:
  1. List your workspaces: orch workspace list
  2. Check the slug spelling
  3. If you were invited, accept the invite first

​
”Not a member of this workspace”

You’re trying to access a workspace you haven’t joined. Fix:
  • Ask the workspace owner to invite you: orch workspace invite [email protected]
  • Check your workspace list: orch workspace list

​
Secrets

​
Secret name validation

Secret names must follow this format: ^[A-Z][A-Z0-9_]*$ 
# Good
orch secrets set STRIPE_SECRET_KEY sk_live_xxx
orch secrets set MY_API_KEY_2 xxx

# Bad
orch secrets set stripe-key xxx       # lowercase, hyphens
orch secrets set 2_THING xxx          # starts with number

​
”Missing secrets” (MISSING_SECRETS)

Your agent requires secrets that aren’t set in the workspace. Fix: 
# List what's configured
orch secrets list

# Add the missing secret
orch secrets set SECRET_NAME value
The agent’s required_secrets in orchagent.json declares which secrets it needs.

​
Schedules

​
Schedule not executing

Checklist:
  1. Is it enabled? orch schedule list
  2. Are LLM keys configured in the workspace?
  3. Test manually: orch schedule trigger <id>
  4. Check recent runs: orch schedule runs <id>

​
Schedule auto-disabled

The schedule hit its consecutive failure threshold and was automatically paused. Fix:
  1. Check recent failures: orch schedule info <id>
  2. Fix the root cause (missing secrets, agent error, timeout)
  3. Re-enable: orch schedule update <id> --enable

​
”No schedule found matching”

The schedule ID prefix is too short or doesn’t match any schedule. Fix: Use a longer prefix, or list schedules to find the ID: 
orch schedule list

​
Services (Always-On)

​
“No runs found” for an always-on agent

Always-on services don’t create discrete “runs” — they’re long-lived processes. If you run orch logs and see “No runs found”, the CLI will suggest active services in your workspace: 
# The CLI auto-suggests services when no runs are found:
orch logs
# → "This workspace has always-on services. To view service logs:"
# →   orch logs discord-bot --live

# View service logs directly
orch logs my-agent --live

# Or use the service logs command for advanced options
orch service logs <service-id>

​
Service stuck in provisioning

Fix:
  1. Check events: orch service info <service-id>
  2. Verify the agent has runtime.command or loop config — direct LLM agents cannot be deployed as services
  3. Check logs for dependency failures: orch service logs <service-id>

​
Service keeps restarting

Fix:
  1. Check crash logs: orch service logs <service-id>
  2. Ensure all required secrets are attached: orch service secret add <id> SECRET_NAME
  3. Verify your process doesn’t exit immediately — it must stay running
  4. Your code must not bind to port 8080 — the health server uses it

​
CRASH-LOOP status

The service was auto-paused after repeated failures. Fix:
  1. Fix the root cause (check logs)
  2. Restart: orch service restart <service-id>

​
Service not updating after orch publish

You published a new version but your running service still has the old code. Cause: Auto-update is workspace-scoped. If you published from workspace A but the service runs in workspace B, the service won’t be updated. Fix: 
# Check which workspace your service is in
orch service list --workspace my-team

# Switch to that workspace, then publish
orch workspace use my-team
orch publish

# Or manually update the service
orch service update <service-id>
orch service restart does not change the version — it only restarts the existing code. Use orch service update to pull a new published version.

​
Deploy fails with 422 after deleting a service

You deleted a service and are trying to redeploy, but it keeps failing with “Service infrastructure rejected the request (code 422).” Cause: The previous service’s infrastructure wasn’t fully cleaned up. Fix: Wait 1-2 minutes and retry. If the error persists, try a different service name or contact support.

​
”No entrypoint found”

The service runner can’t detect which file to run. Fix:
  • Add a main.py or index.js to your project root
  • Or set runtime.command in orchagent.json: 
    { "runtime": { "command": "python main.py" } }

​
LLM Provider Errors

​
”Invalid OpenAI/Anthropic/Gemini API key”

Your stored LLM key is invalid. Fix:
  • Cloud runs: Update your key in Settings > LLM Keys
  • Local runs: Update the environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY)

​
“Failed to decrypt LLM key”

Your stored key couldn’t be decrypted (server-side encryption key may have rotated). Fix: Delete and re-add your key in Settings > LLM Keys.

​
Provider-specific errors

ErrorMeaningFix
OpenAI 429Rate limitedWait, or switch: --provider anthropic
Anthropic 529OverloadedWait, or switch: --provider openai
Gemini 403Access deniedCheck API key permissions in Google Cloud
Ollama 404Model not foundRun ollama pull <model> locally
Ollama 502Connection failedStart Ollama: ollama serve

​
Orchestration

​
”Dependency not declared in manifest”

An agent tried to call another agent that isn’t listed in its manifest.dependencies. Fix: Add the dependency to orchagent.json: 
{
  "manifest": {
    "dependencies": {
      "scanner": "acme/scanner@latest"
    }
  }
}
Then republish.

​
”Agent is not callable” (AGENT_NOT_CALLABLE)

The target agent has callable: false and can’t be invoked by other agents. Fix: Agents are callable by default. If the target agent has "callable": false set explicitly, remove it (or set to true) and republish.

​
”Max hops exceeded”

The orchestration chain is too deep. Fix: Increase max_hops in the caller’s manifest, or simplify the agent chain. Check the chain depth with: 
orch tree acme/my-orchestrator

​
Network & Connectivity

​
”Unable to connect” / Network errors (exit code 9)

The CLI can’t reach the orchagent API. Causes:
  • No internet connection
  • Firewall/proxy blocking api.orchagent.io
  • Platform outage
Fix:
  1. Check your connection: curl https://api.orchagent.io/health
  2. Check platform status: orch status
  3. If behind a proxy, configure HTTPS_PROXY environment variable

​
Server errors (5xx, exit code 8)

A platform error occurred. Fix: Wait a moment and retry. If it persists, check platform status or contact support with the request_id from the error output.

​
Local Execution

​
”Python 3 is required for local agent execution”

Local agent execution needs Python 3 installed. Fix: Install Python 3 from python.org/downloads

​
”Failed to install dependencies”

pip install failed during local sandbox setup. Fix:
  1. Check your requirements.txt installs cleanly: pip install -r requirements.txt
  2. Ensure you have the right Python version
  3. For system-level dependencies, install them manually first

​
”Failed to run unzip”

The CLI needs unzip to extract agent bundles. Fix: 
# macOS (included by default)
# Linux
sudo apt install unzip
# or
sudo yum install unzip

​
Exit Code Reference

CodeMeaningCommon Fix
0Success—
1General errorRead the error message
2Auth error (401)Run orch login
3Permission denied (403)Check workspace/agent access
4Not found (404)Check agent reference format
5Invalid inputCheck your JSON/flags
6Rate limited (429)Wait and retry, or upgrade
7TimeoutSimplify input or increase timeout
8Server error (5xx)Retry, check status
9Network errorCheck connectivity
Use exit codes in scripts: 
orch run acme/agent --data '{}' --json 2>/dev/null
if [ $? -eq 6 ]; then
  echo "Rate limited, retrying in 60s..."
  sleep 60
fi

​
Error Response Format

​
CLI Errors (with --json)

When --json is active (explicit flag or auto-detected non-TTY), all CLI errors are structured JSON on stdout: 
{
  "error": true,
  "code": "NOT_FOUND",
  "message": "Agent 'acme/scanner' not found",
  "hint": "Run `orch agents` to list your agents",
  "exit_code": 4
}
FieldTypeDescription
errortrueAlways true — distinguishes errors from success output
codestringMachine-readable error code (see table below)
messagestringHuman-readable error description
hintstring?Optional suggestion for how to fix the error
exit_codenumberExit code the process will exit with
Error codes:
CodeMeaning
GENERAL_ERRORUnknown/unclassified error
AUTH_REQUIREDNot logged in or invalid API key
PERMISSION_DENIEDInsufficient permissions (403)
NOT_FOUNDAgent, version, or resource not found (404)
INVALID_INPUTValidation error, bad JSON, invalid flags
RATE_LIMITEDToo many requests (429)
TIMEOUTOperation timed out
SERVER_ERRORServer-side error (5xx)
NETWORK_ERRORUnable to connect
Gateway-specific error codes (e.g. AGENT_NOT_FOUND, MISSING_BILLING_ORG) pass through from the API when available. Use in scripts: 
# Parse structured errors with jq
output=$(orch run acme/scanner doc.pdf --json 2>/dev/null)
if echo "$output" | jq -e '.error' > /dev/null 2>&1; then
  echo "Error: $(echo "$output" | jq -r '.code')"
fi

​
API Errors (Gateway)

API errors return a structured JSON response: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "is_retryable": true,
    "suggested_wait_time": 30
  },
  "metadata": {
    "request_id": "req_abc123"
  }
}
When contacting support, include the request_id — it helps us locate your exact request in our logs.

​
FAQ

​
What’s the difference between pull, install, and fork?

These three commands do very different things:
CommandWhat it doesWhat it writes to disk
orch installWires an agent into your IDE as a sub-agentOnly IDE config files (e.g. .claude/agents/my-agent.md, .cursor/rules/my-agent.mdc)
orch pullDownloads the agent’s full source projectSource files: orchagent.json, prompt.md, schema.json, code bundle
orch forkCopies the agent into your workspace on the serverNothing locally — creates a server-side copy you own
Key point: orch install does not put the agent’s source code on your machine. It generates a config file that tells your AI tool (Claude Code, Cursor, etc.) how to delegate to that agent. The agent’s prompt, manifest, schemas, and code are not written as separate files.

​
When should I use each one?

  • orch install — You want Claude Code or Cursor to be able to call this agent as a sub-agent. You don’t need the source.
  • orch pull — You want the source files so you can edit, customize, and republish your own version.
  • orch fork — You want your own server-side copy of a public agent in your workspace, which you can then customize via orch pull, edit, and republish.

​
Do I need to fork before pulling?

No. If the agent is public and has local download enabled, you can orch pull it directly. Forking is only needed if you want a private server-side copy in your workspace that you can deploy independently.

​
Can I orch install any public agent?

Yes. orch install fetches the agent’s metadata and converts it to an IDE config file. It works for any public agent regardless of the allow_local_download setting, because it only needs metadata — not the full source.

​
Still Stuck?