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

# Troubleshoot the Straddle CLI

> Resolve installation, credentials, account context, incomplete data, and automation errors.

Start with the version, credential source, and effective context:

```bash theme={null}
straddle version
straddle auth status --json
straddle agent-context --pretty
```

For connectivity and local-store diagnostics, run `straddle doctor --json`. Doctor makes a reachability request to the configured API host. Its credential-presence result needs a successful resource read to confirm authorization.

## The shell can't find the command

Add the installation directory to `PATH` and open a new terminal. The shell installer uses `~/.local/bin` by default. For npm, confirm the global binary directory is on `PATH` and optional dependencies were installed. See [installation methods](/developer-tools/cli/install).

## The API key is rejected

Check `auth status` for the credential source. An exported `STRADDLE_API_KEY` overrides a token saved with `auth set-token`. Pair a sandbox key with sandbox and a production key with production.

Inspect `runtime_context.environment` in `agent-context`. If it differs from `STRADDLE_ENVIRONMENT`, check `STRADDLE_BASE_URL` and the configuration file's `base_url`. After correcting the configuration, verify a fresh read:

```bash theme={null}
straddle customers list --page-size 1 --data-source live --no-cache --json
```

## An account-scoped command is rejected

Inspect the saved integration type and account:

```bash theme={null}
straddle setup
straddle use-account
```

For a platform's account-level work, select the intended account with `straddle use-account ACCOUNT_ID`. Direct business integrations use `setup --type account` and omit `--account`.

An explicit `--account` is rejected on operations that don't accept the account header. A profile can supply that flag too. Inspect the profile without applying it: `straddle profile show PROFILE_NAME`. See [account context](/developer-tools/cli/auth-context) for the setup path.

## Local results are missing or older than expected

Confirm that sync and the query use the same API environment, acting account, and database path. An empty acting account selects its own data, rather than every account.

Inspect the last sync's resource events and `sync_summary`. Access warnings, filters, or a page cap can leave the data incomplete even when sync exits successfully. Follow [sync completeness checks](/developer-tools/cli/local-data#check-sync-completeness), then rerun the resources needed for your task.

If diagnostics report `hidden_legacy_records`, resync in the intended context. For a fresh API read instead of local analysis, use `--data-source live --no-cache`.

## An agent receives unexpected output

Use `--agent` for compact JSON or `--json` for full JSON output. Add `--compact=false` to agent mode when you need fields omitted by compact output. Resource output remains JSON when piped, including with `--human-friendly`.

Parse `sync` as newline-delimited JSON events, not a single object. Keep stderr separate from stdout; errors and request previews can appear there as text. See [agent output modes](/developer-tools/cli/agent-use#choose-an-output-mode).

## Respond to an error

Use the exit code and diagnostics to choose the next action:

| Exit code | Meaning | Next action |
| - | - | - |
| `1` | General command failure | Read stderr and any resource-level events. |
| `2` | Invalid command or arguments | Check the command's `--help` and correct inputs. |
| `3` | Resource not found | Check its ID, environment, and account. |
| `4` | Authentication or permission error | Check the key's source, environment, and permitted resources. |
| `5` | API error | Read the status and response details; resolve the reported condition. |
| `6` | Partial failure detected in a response | Inspect the reported successful and failed operations before retrying. |
| `7` | Rate limited | Wait before retrying and reduce request frequency. |
| `10` | Configuration error | Correct the reported configuration file or environment variable. |

A timeout during a write can leave the result uncertain. Check the resource's current state before retrying. For a request that supports an idempotency key, retain the same key when retrying the same operation.


## Related topics

- [Troubleshoot Straddle skills](/developer-tools/skills/troubleshooting.md)
- [Install the Straddle CLI](/developer-tools/cli/install.md)
- [Troubleshoot MCP](/developer-tools/mcp/troubleshooting.md)
- [Use the CLI with coding agents](/developer-tools/cli/agent-use.md)
- [Zapier integration for Straddle webhooks](/integrations/webhooks/zapier.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.