Skip to main content
Start with the version, credential source, and effective context:
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.

​
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:

​
An account-scoped command is rejected

Inspect the saved integration type and 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 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, 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.

​
Respond to an error

Use the exit code and diagnostics to choose the next action: 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.