# Troubleshooting (/cli/troubleshooting) Start by checking the version and resolved settings: ```bash sim --version sim whoami --no-verify sim whoami ``` `--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](/cli/scripting#exit-codes). ## A command targets the wrong workspace or deployment \[#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: ```bash sim whoami --no-verify --profile ``` After OAuth login, set a default with `sim configure --set-workspace `. 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](/cli/configuration#where-settings-come-from) for the full precedence rules. ## An error ends in `— run: sim login --profile ` \[#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: ```bash sim whoami --no-verify --profile ``` For a stored OAuth login, logout is required before a new login: ```bash sim logout --profile sim login --profile ``` `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 \[#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](/cli/authentication#where-the-login-is-stored). ## `Could not reach https://www.sim.ai: ` \[#could-not-reach-httpswwwsimai-reason] DNS, TLS, a proxy, or an unavailable self-hosted service can prevent a response. Check the resolved endpoint's scheme and port: ```bash sim whoami --no-verify sim configure --set-endpoint http://localhost:3000 --profile local ``` Loopback development endpoints can use HTTP. Remote browser sign-in requires HTTPS for OAuth and pairing. ### Endpoint redirects \[#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 \[#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](/cli/configuration#registry-and-proxy-behavior). ## A JSON flag rejects a value that looks like valid JSON \[#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: ```bash sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter '{"all":[{"field":"status","op":"eq","value":"open"}]}' sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter @filter.json ``` 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](/cli/scripting). ## A value looks truncated \[#a-value-looks-truncated] Table display clips long cells. Select JSON/YAML to inspect the returned values: ```bash sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --output json ``` 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 \[#in-an-interactive-terminal-sim-files-get-refuses-to-print-to-the-terminal] Binary content must go to a file or a pipe: ```bash sim files get wf_8Kd2NpVrY6zTfQa3XwBmS -o ./image.png sim files get wf_8Kd2NpVrY6zTfQa3XwBmS | shasum ``` An existing output file requires `--force`. With `--output-file`, file content is saved and stdout contains a save receipt. See [File commands](/cli/files). ## A stored output format is invalid \[#a-stored-output-format-is-invalid] Use an environment override to repair the saved default: ```bash SIM_OUTPUT=json sim configure --set-output json SIM_OUTPUT=json sim configure --profile --set-output json ``` `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 \[#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: ```bash sim --version sim --help sim update ``` `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: ```bash bun add -g sim@latest ``` 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](/cli/configuration#updates) for supported managers and copy-detection behavior. ## An update notice appears in output I am parsing \[#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: ```bash export SIM_NO_UPDATE_CHECK=1 ``` 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 \[#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](/cli/workflow-sync#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 \[#anything-else] For an unexpected stack trace, [open an issue](https://github.com/simstudioai/sim/issues) 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. ## Related docs \[#related-docs] - [Authentication](/cli/authentication) - [Configuration](/cli/configuration) - [Output formats](/cli/output) - [Scripting](/cli/scripting)