Troubleshooting - orchagent

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.

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)

The browser auth flow uses a local callback server. If it hangs:

Check your firewall isn’t blocking localhost ports
Try a specific port: orch login --port 8910
Fall back to key-based login: orch login --key sk_live_xxx
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:

Run with verbose to see sandbox output:

orch run acme/my-agent --verbose --data '{}'

Test locally:
echo '{}' | python main.py
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:

Read the error message — it’s your agent’s stderr (truncated to 500 chars)
Check for missing dependencies in requirements.txt
Test locally: orch run --local acme/my-agent --data '{}'
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:

Verify requirements.txt installs cleanly: pip install -r requirements.txt
Pin specific versions to avoid conflicts
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:

Check the schema: orch schema acme/agent (or orch info acme/agent)
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:

List your workspaces: orch workspace list
Check the slug spelling
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:

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

Schedule auto-disabled

The schedule hit its consecutive failure threshold and was automatically paused. Fix:

Check recent failures: orch schedule info <id>
Fix the root cause (missing secrets, agent error, timeout)
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:

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

Service keeps restarting

Fix:

Check crash logs: orch service logs <service-id>
Ensure all required secrets are attached: orch service secret add <id> SECRET_NAME
Verify your process doesn’t exit immediately — it must stay running
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:

Fix the root cause (check logs)
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

Error	Meaning	Fix
OpenAI 429	Rate limited	Wait, or switch: `--provider anthropic`
Anthropic 529	Overloaded	Wait, or switch: `--provider openai`
Gemini 403	Access denied	Check API key permissions in Google Cloud
Ollama 404	Model not found	Run `ollama pull <model>` locally
Ollama 502	Connection failed	Start 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:

Check your connection: curl https://api.orchagent.io/health
Check platform status: orch status
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:

Check your requirements.txt installs cleanly: pip install -r requirements.txt
Ensure you have the right Python version
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

Code	Meaning	Common Fix
`0`	Success	—
`1`	General error	Read the error message
`2`	Auth error (401)	Run `orch login`
`3`	Permission denied (403)	Check workspace/agent access
`4`	Not found (404)	Check agent reference format
`5`	Invalid input	Check your JSON/flags
`6`	Rate limited (429)	Wait and retry, or upgrade
`7`	Timeout	Simplify input or increase timeout
`8`	Server error (5xx)	Retry, check status
`9`	Network error	Check 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
}

Field	Type	Description
`error`	`true`	Always `true` — distinguishes errors from success output
`code`	`string`	Machine-readable error code (see table below)
`message`	`string`	Human-readable error description
`hint`	`string?`	Optional suggestion for how to fix the error
`exit_code`	`number`	Exit code the process will exit with

Error codes:

Code	Meaning
`GENERAL_ERROR`	Unknown/unclassified error
`AUTH_REQUIRED`	Not logged in or invalid API key
`PERMISSION_DENIED`	Insufficient permissions (403)
`NOT_FOUND`	Agent, version, or resource not found (404)
`INVALID_INPUT`	Validation error, bad JSON, invalid flags
`RATE_LIMITED`	Too many requests (429)
`TIMEOUT`	Operation timed out
`SERVER_ERROR`	Server-side error (5xx)
`NETWORK_ERROR`	Unable 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:

Command	What it does	What it writes to disk
`orch install`	Wires an agent into your IDE as a sub-agent	Only IDE config files (e.g. `.claude/agents/my-agent.md`, `.cursor/rules/my-agent.mdc`)
`orch pull`	Downloads the agent’s full source project	Source files: `orchagent.json`, `prompt.md`, `schema.json`, code bundle
`orch fork`	Copies the agent into your workspace on the server	Nothing 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?

Run orch doctor --verbose for a full diagnostic
Check the Discord community for help
Open an issue on GitHub
Email [email protected] with the request_id from your error

​First Step: Run Doctor

​Authentication & Login

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

​“Authentication failed” (exit code 2)

​“Access denied” (403)

​Login hangs or times out

​Running Agents

​”Agent not found” (404)

​”Invalid agent reference”

​“No LLM key found” / LLM_KEY_REQUIRED

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

​SANDBOX_ERROR (code_error)

​SANDBOX_ERROR (setup_error)

​SANDBOX_TIMEOUT

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

​”Rate limit exceeded” (429)

​LLM_RATE_LIMITED

​”Budget limit reached” (BUDGET_EXCEEDED)

​JSON Input Errors

​”Invalid JSON in —data option”

​“Missing required field”

​Publishing

​”No orchagent.json found”

​”No prompt.md found”

​Agent name validation errors

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

​“Unpublished dependencies”

​”Publish blocked by security scan” (SECURITY_BLOCKED)

​Schema mismatch warning

​Workspaces

​”No workspace specified”

​“Workspace not found”

​”Not a member of this workspace”

​Secrets

​Secret name validation

​”Missing secrets” (MISSING_SECRETS)

​Schedules

​Schedule not executing

​Schedule auto-disabled

​”No schedule found matching”

​Services (Always-On)

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

​Service stuck in provisioning

​Service keeps restarting

​CRASH-LOOP status

​Service not updating after orch publish

​Deploy fails with 422 after deleting a service

​”No entrypoint found”

​LLM Provider Errors

​”Invalid OpenAI/Anthropic/Gemini API key”

​“Failed to decrypt LLM key”

​Provider-specific errors

​Orchestration

​”Dependency not declared in manifest”

​”Agent is not callable” (AGENT_NOT_CALLABLE)

​”Max hops exceeded”

​Network & Connectivity

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

​Server errors (5xx, exit code 8)

​Local Execution

​”Python 3 is required for local agent execution”

​”Failed to install dependencies”

​”Failed to run unzip”

​Exit Code Reference

​Error Response Format

​CLI Errors (with --json)

​API Errors (Gateway)

​FAQ

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

​When should I use each one?

​Do I need to fork before pulling?

​Can I orch install any public agent?

​Still Stuck?

First Step: Run Doctor

Authentication & Login

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

“Authentication failed” (exit code 2)

“Access denied” (403)

Login hangs or times out

Running Agents

”Agent not found” (404)

”Invalid agent reference”

“No LLM key found” / LLM_KEY_REQUIRED

“Agent exited with code X (no output)”

SANDBOX_ERROR (code_error)

SANDBOX_ERROR (setup_error)

SANDBOX_TIMEOUT

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

”Rate limit exceeded” (429)

LLM_RATE_LIMITED

”Budget limit reached” (BUDGET_EXCEEDED)

JSON Input Errors

”Invalid JSON in —data option”

“Missing required field”

Publishing

”No orchagent.json found”

”No prompt.md found”

Agent name validation errors

”runtime.command and loop cannot both be set”

“Unpublished dependencies”

”Publish blocked by security scan” (SECURITY_BLOCKED)

Schema mismatch warning

Workspaces

”No workspace specified”

“Workspace not found”

”Not a member of this workspace”

Secrets

Secret name validation

”Missing secrets” (MISSING_SECRETS)

Schedules

Schedule not executing

Schedule auto-disabled

”No schedule found matching”

Services (Always-On)

“No runs found” for an always-on agent

Service stuck in provisioning

Service keeps restarting

CRASH-LOOP status

Service not updating after `orch publish`

Deploy fails with 422 after deleting a service

”No entrypoint found”

LLM Provider Errors

”Invalid OpenAI/Anthropic/Gemini API key”

“Failed to decrypt LLM key”

Provider-specific errors

Orchestration

”Dependency not declared in manifest”

”Agent is not callable” (AGENT_NOT_CALLABLE)

”Max hops exceeded”

Network & Connectivity

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

Server errors (5xx, exit code 8)

Local Execution

”Python 3 is required for local agent execution”

”Failed to install dependencies”

”Failed to run unzip”

Exit Code Reference

Error Response Format

CLI Errors (with `--json`)

API Errors (Gateway)

FAQ

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

When should I use each one?

Do I need to fork before pulling?

Can I `orch install` any public agent?

Still Stuck?