Start by checking the version and resolved settings:
--no-verify stays offline. Normal whoami checks authentication and access to the selected workspace. Inspect its verification result before changing credentials.
Most command failures exit 1. Verification, run waiting, and workspace-operation waiting have additional outcomes; see Exit codes.
A command targets the wrong workspace or deployment
Flags override the environment, which overrides profile defaults. A stale SIM_WORKSPACE can outrank the workspace saved in your profile. whoami shows each winning value and source:
After OAuth login, set a default with sim configure --set-workspace <id>. Pairing sets the default chosen on its approval page. A default target does not restrict credential scope; --workspace can select another accessible workspace.
See Configuration for the full precedence rules.
An error ends in — run: sim login --profile <name>
A 401 means the API rejected authentication. The credential may be revoked, expired, or issued by another deployment. Check the endpoint before signing in again:
For a stored OAuth login, logout is required before a new login:
whoami exit 1 can also mean a valid credential cannot access the selected workspace, or the workspace does not exist. A 403/404 workspace refusal needs an access or target correction rather than repeated login.
OAuth refresh or endpoint mismatch
An OAuth login cannot move to another deployment. Restore its original endpoint, or log out before configuring a new one. Workspace profiles share their authentication profile's endpoint.
Sign in separately on each machine. Copied credential files can reuse one single-use refresh family and cause revocation. If a refresh response was lost, the CLI will not retry the consumed token; log out and sign in again. See Stored logins.
Could not reach https://www.sim.ai: <reason>
DNS, TLS, a proxy, or an unavailable self-hosted service can prevent a response. Check the resolved endpoint's scheme and port:
Loopback development endpoints can use HTTP. Remote browser sign-in requires HTTPS for OAuth and pairing.
Endpoint redirects
The CLI does not follow API redirects: they can change a write's method/body or forward a credential to another origin. Configure the actual API endpoint shown by the error. The hosted default is https://www.sim.ai.
Proxy settings
Node must opt in before fetch uses HTTP(S)_PROXY. Set NODE_USE_ENV_PROXY=1 before launching the CLI, using Node 22.21+ or 24.0+. The equivalent --use-env-proxy Node flag requires 22.21+ or 24.5+. Older runtimes need an upgrade. See Registry and proxy behavior.
A JSON flag rejects a value that looks like valid JSON
A shell may consume unquoted JSON quotes. Quote the whole value or read JSON from a file:
Workflow imports require JSON, even if an export was saved as YAML. File-aware flags interpret @value as a path; write @@value for a literal leading @. See Scripting.
A value looks truncated
Table display clips long cells. Select JSON/YAML to inspect the returned values:
Changing format does not remove server-side caps. Check any reported truncation flag/notice, filters, and pagination before assuming the response contains everything.
In an interactive terminal, sim files get refuses to print to the terminal
Binary content must go to a file or a pipe:
An existing output file requires --force. With --output-file, file content is saved and stdout contains a save receipt. See File commands.
A stored output format is invalid
Use an environment override to repair the saved default:
configure rejects global --output, --endpoint, and --workspace; persistence uses --set-*. If an invalid environment variable caused the error, correct or unset it as well.
A command is missing that the documentation describes
Compare the installed version and command help. These docs describe the current source; an older installed CLI or self-hosted server can lack an operation:
sim update verifies the active global installation and preserves its stable/staging/dev channel. If an older Bun installation has no update command, update the package through Bun:
Use the corresponding staging/dev tag for an intentional prerelease installation. Installations made with npm, pnpm, or Yarn Classic should be upgraded through their original manager; a different manager can create another executable on PATH. Project-local and temporary package-runner copies must be updated through their package manager too.
See Updates for supported managers and copy-detection behavior.
An update notice appears in output I am parsing
Notices go to stderr, so a JSON stdout pipe is unaffected. If your runner combines streams, separate stdout/stderr or suppress automatic checks:
Checks are already quiet in CI and when stderr is redirected. Manual sim update remains available when notices are disabled.
A sync apply or wait did not return a clear outcome
Retain the original request/operation IDs and exact input. An operation may have committed even when its response was lost or its follow-up copying/deployment failed. Query it in the receipt workspace or retry only identical input with the original request ID. See Reconcile completion and retries.
A workflow wait timeout also leaves its run active. Inspect that run ID; do not assume another execution is a retry of the same work.
Anything else
For an unexpected stack trace, open an issue with the CLI version, command, sanitized trace, and relevant resolved settings. Remove credentials, sensitive inputs, and private file contents before posting. Debug output can contain request selectors.