> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and how to fix them

## First Step: Run Doctor

Before diving into specific errors, run the built-in diagnostic:

```bash theme={null}
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:

```bash theme={null}
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:**

```bash theme={null}
# 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:**

```bash theme={null}
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](https://orchagent.io/settings)

***

## 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:**

```bash theme={null}
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:**

```bash theme={null}
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](https://orchagent.io/settings), or pass inline:

```bash theme={null}
orch run acme/agent --key sk-... --provider openai
```

**For local runs (`--local`):**

Set the environment variable for your provider:

```bash theme={null}
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:
   ```bash theme={null}
   orch run acme/my-agent --verbose --data '{}'
   ```
2. Test locally:
   ```bash theme={null}
   echo '{}' | python main.py
   ```
3. Check logs in the [dashboard](https://orchagent.io/dashboard) or via CLI:
   ```bash theme={null}
   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](/building-agents/environments)

### 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`:
  ```json theme={null}
  { "timeout_seconds": 120 }
  ```
* Check if you're on the Free tier (30s tool / 2 min agent limit) — [upgrade](https://orchagent.io/plans) 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):

```bash theme={null}
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](https://orchagent.io/plans) for higher limits
* See [Rate Limits](/concepts/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](https://orchagent.io/settings)
* 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):**

```bash theme={null}
orch run acme/agent --data '{"text": "hello"}'
```

**Fix — use a file instead:**

```bash theme={null}
echo '{"text": "hello"}' > input.json
orch run acme/agent --data @input.json
```

**Fix — use stdin:**

```bash theme={null}
echo '{"text": "hello"}' | orch run acme/agent --data @-
```

**PowerShell fix:**

```powershell theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
# 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:**

```bash theme={null}
# 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 you@email.com`
* Check your workspace list: `orch workspace list`

***

## Secrets

### Secret name validation

Secret names must follow this format: `^[A-Z][A-Z0-9_]*$`

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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:**

```bash theme={null}
# 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>
```

<Note>
  `orch service restart` does **not** change the version — it only restarts the existing code. Use `orch service update` to pull a new published version.
</Note>

### 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`:
  ```json theme={null}
  { "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](https://orchagent.io/settings)
* **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](https://orchagent.io/settings).

### 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`:

```json theme={null}
{
  "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:

```bash theme={null}
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](https://status.orchagent.io) 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](https://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:**

```bash theme={null}
# 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](https://orchagent.io/plans) |
| `7`  | Timeout                 | Simplify input or increase timeout                       |
| `8`  | Server error (5xx)      | Retry, check [status](https://status.orchagent.io)       |
| `9`  | Network error           | Check connectivity                                       |

Use exit codes in scripts:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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](https://discord.gg/orchagent) for help
* Open an issue on [GitHub](https://github.com/orchagent/orchagent/issues)
* Email [support@orchagent.io](mailto:support@orchagent.io) with the `request_id` from your error