> For the complete documentation index, see [llms.txt](https://docs.sqai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sqai.com/reference/troubleshooting.md). # Troubleshooting SQAI never throws a raw stack trace. Every failure is a typed `SqaiError` carrying `{ code, message, retryable, request_id }` plus `source` and structured `details`. `source: "engine"` means the SQAI runtime rejected the request and its code passes through verbatim; `source: "sqai"` means the SDK stopped it before dispatch. Codes are stable snake\_case — a code is never renamed and the same condition never gets two codes. The query plane runs in-process: no separate service, nothing to provision, so it never raises a runtime error. Local compute requires one free `sqai login` device enrollment, then provisions the managed runtime exactly **once** — the first-ever `compute()` spends \~110s to download, verify (pinned sha256 + signed manifest), extract, and start the runtime — then stays **warm and resident on your machine**. Every later call is warm: `finance.npv` returns in \~0.9ms. There is **no per-query cold start**; a slow first call is the one-time setup, not a bug. {% hint style="info" %} Hit an error? Run `sqai doctor --json` first. It prints Node / SDK / contract / runtime / parity checks as one JSON object and exits non-zero on any failure. `sqai runtime status --json` shows whether the runtime is warm. Every code below maps to one fix. {% endhint %} ## Every code, one fix | Code | Source | One-line fix | | ---------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `unsupported_platform` | sqai | No managed bundle for your OS/arch — set `SQAI_DEPLOYMENT_URL` to run compute on a private SQAI deployment. | | `login_required` | sqai | Run `sqai login` once for the free `sqai_developer` device key, or set `SQAI_API_KEY` in the process. | | `runtime_provision_failed` | sqai | Managed runtime couldn't install/start — read `details.reason`, then `sqai runtime install`. | | `daemon_port_conflict` | sqai | Runtime process couldn't bind its socket/port — `sqai runtime stop` (or free the port), then retry. | | `compute_runtime_unavailable` | sqai / runtime | No compute backend reachable — wait out the one-time provision, or set `SQAI_DEPLOYMENT_URL` for a private SQAI deployment. Retryable. | | `contract_mismatch` | sqai | Runtime's contract hash ≠ the embedded one — align SDK and SQAI versions; check `sqai doctor`. | | `seed_required` | sqai | Simulation capability called without a seed — pass `seed`. | | `unsupported_operation` | sqai | Capability isn't in the read-only deterministic surface (or the name is unknown) — use a listed one; see `details.nearest_matches`. | | `invalid_intent` | sqai | Malformed computation (wrong arg count/type, missing or unknown param) — match the signature. | | `duplicate_argument_binding` | sqai | A parameter was supplied twice across args/kwargs/bindings — supply each exactly once. | | `policy_denied_source` | sqai | Source not in `allowedSources` — add it to the policy. | | `policy_denied_field` | sqai | Field not in `allowedFields` for that source — add it. | | `policy_denied_function` | sqai | Capability not in `allowedFunctions` — add it (must be read-only deterministic). | | `source_already_registered` | sqai | A name was re-connected to different data — pick a new name; connected sources are immutable. | | `result_not_found` | sqai | Stored result missing, expired, or wrong principal — re-run; results are TTL'd per tenant. | | `network_error` · `timeout` · `rate_limited` · `service_unavailable` · `quota_exhausted` | runtime | Transient private SQAI deployment failures — retry with backoff. Retryable. | ## Runtime provisioning
unsupported_platform — no bundle for your OS/arch The managed runtime ships as a signed per-platform bundle. If none is published for your `platform-arch` (the current tested pair is `darwin-arm64`, bundle `0.1.0`, sha256 `4d64142e…`), local compute can't provision. ``` No managed runtime bundle is published for 'linux-x64'. ``` `details` carries `{ platform, supported }`. **Fix:** run where a bundle exists, or point at a private SQAI deployment — set `SQAI_DEPLOYMENT_URL` (with `SQAI_API_KEY` only if your SQAI deployment requires auth). The query plane is unaffected; it needs no runtime.
runtime_provision_failed — install or start failed One code, many reasons — always in `details.reason` (printed first by `sqai runtime install`): | `details.reason` | Meaning | Fix | | ------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `bundle_sha256_mismatch` | Downloaded tarball didn't match the contract's pinned sha256 (corrupt or tampered). | Re-run `sqai runtime install`; never bypass the check. | | `download_failed` | Bundle couldn't be fetched. Retryable. | Check network, retry. | | `rollback_protected` | Bundle version is below the minimum accepted (downgrade blocked). | Use a runtime ≥ the min version. | | `daemon_unhealthy` | Bundle installed but the runtime never reported a usable runtime. | Check runtime logs, retry. | | `install_rename_failed` | Verified bundle couldn't be moved into place. | Check cache-dir permissions/disk. | | `no_build_service` | `runtimeModules` set with no build service. | Set `SQAI_BUILD_SERVICE_URL`, or omit `runtimeModules` to use the default bundle. | Auto-install disabled? You'll see: ``` Automatic runtime installation is disabled (SQAI_RUNTIME_AUTO_INSTALL=0). Install manually with `sqai runtime install`. ``` **Fix:** unset `SQAI_RUNTIME_AUTO_INSTALL=0`, or run `sqai runtime install`. Signature/trust failures (bad or revoked signing key) surface here too — those mean the bundle is untrusted; do not force it.
daemon_port_conflict — socket/port already held The runtime binds a deterministic per-runtime socket and TCP port so a filtered runtime never collides with the default. If the endpoint is already held by a stale runtime process, provisioning fails here. **Fix:** `sqai runtime stop` to release it, or free the port, then retry. `sqai runtime status --json` shows whether a runtime process is already `managed` by this process.
## Compute dispatch
compute_runtime_unavailable — no backend reachable Raised when the local runtime isn't up yet or a private SQAI deployment is unreachable. This is **retryable** — the common case is the first call still doing its one-time provision. ``` Your private SQAI deployment is unreachable: . Check SQAI_DEPLOYMENT_URL / SQAI_API_KEY. ``` **Fix:** for local mode, let the one-time provision finish (\~110s) — every call after is warm. For private SQAI deployment mode, set `SQAI_DEPLOYMENT_URL` (with `SQAI_API_KEY` if your SQAI deployment requires auth). HTTP 429 from a private SQAI deployment arrives as `quota_exhausted` (source `engine`, retryable).
contract_mismatch — runtime runs a different contract The SQAI deployment advertises a capability-contract hash that differs from the one embedded in your SDK. Every result is stamped with `contract_hash` (`sha256:79f1c5a6…` for this build) so drift is detectable, not silent. **Fix:** align SDK and SQAI versions. `sqai doctor` cross-checks the embedded contract against `tested-pair.json` and reports `MISMATCH vs embedded contract: capability_contract_hash` when they diverge.
## Computation validation These are caught by the SDK before anything is dispatched — the model can't compute past them.
seed_required — a simulation needs a seed 10 of the 4,574 exposed capabilities are seed-required simulations. Called without a seed: ``` '' is a simulation capability: a seed is required so results are replayable. ``` **Fix:** pass `seed`. With a seed the result is deterministic and its `computation_hash` is reproducible.
unsupported_operation — not on the surface Of 4,778 total capabilities, 4,574 are exposed to TS/Python/AI-SDK — all read-only and deterministic (or deterministic-when-seeded). The rest are not. You hit this when the name is unknown, or the capability isn't read-only deterministic (e.g. a struct-returning capability outside the exposed signature set): ``` Unknown capability 'finance.npvv'. ``` `details.nearest_matches` suggests the closest real names. **Fix:** call a listed capability — browse with `searchCapabilities` / `listSources` (each now carries a one-line `summary`).
invalid_intent — malformed computation Wrong positional count, unknown parameter, missing required parameter, or a wire-type mismatch: ``` 'finance.npv' takes at most 2 arguments; got 3 positional. 'finance.npv' has no parameter 'rat'. 'finance.npv' is missing required parameter 'rate'. Parameter 'rate' of 'finance.npv' expects float64. ``` **Fix:** match the capability's signature (name, arity, and types).
duplicate_argument_binding — a parameter set twice Every parameter must be supplied through exactly one of `args`, `kwargs`, or `bindings`. SQAI never silently overwrites: ``` Parameter 'cashflows' of 'finance.npv' was supplied through both kwargs and bindings. ``` **Fix:** supply each parameter once.
## Policy and sources
policy_denied_source · policy_denied_field · policy_denied_function Application policy is pre-execution and un-overridable. A request outside the enabled subset is denied: ``` Source 'payroll' is not allowed by policy. Field 'ssn' on source 'employees' is not allowed by policy. Capability 'finance.npv' is not allowed by policy. ``` **Fix:** add the source/field/capability to `allowedSources` / `allowedFields` / `allowedFunctions`. Policy can only narrow the read-only surface, never widen it — a non-read-only capability still fails `unsupported_operation`.
source_already_registered — sources are immutable `connect()` binds a name to a schema revision for the life of the process. Re-connecting the same name to different data is rejected: ``` Source 'sales' is already registered; connected sources are immutable. ``` Re-connecting identical data returns the existing source. **Fix:** use a different name for different data.
result_not_found — stored result gone or wrong principal Stored results are TTL'd and scoped per tenant; a lookup from the wrong principal returns the same `result_not_found` as an expired one — by design, so it never leaks existence. ``` No such result for this principal. ``` **Fix:** re-run the computation, or fetch with the same principal before the TTL expires.
## Diagnose in order {% stepper %} {% step %} #### Check the environment ```bash sqai doctor --json ``` Verifies Node ≥ 20, that `@thyn-ai/sqai` imports, and that the embedded contract loads (`4778 capabilities, sha256:79f1c5a6…`). Non-zero exit means one check failed — read `checks[].detail`. {% endstep %} {% step %} #### Check the runtime ```bash sqai runtime status --json ``` `runtime_available: true` means the runtime is warm — compute will be sub-millisecond. `false` means the next `compute()` will provision (\~110s, once). {% endstep %} {% step %} #### Provision or repair ```bash sqai runtime install # download → verify → extract → start; structured failure on any step sqai runtime verify # print the pinned bundle version + per-platform sha256 sqai runtime stop # release a stale runtime process endpoint ``` Every failure prints `code`, `message`, and `details.reason` — never a stack trace. {% endstep %} {% step %} #### Confirm parity (optional) ```bash sqai doctor --parity --strict ``` Asserts every exposed capability is read-only deterministic and, against a live runtime, that the contract's modules match `list_modules`. `--strict` fails if no runtime is reachable. {% endstep %} {% endstepper %} ## Catch it in code Inspect `code`, `source`, `retryable`, and `request_id` on the typed error — never parse the message. {% tabs %} {% tab title="TypeScript" icon="js" %} ```ts import { SqaiError } from "@thyn-ai/sqai"; try { await sqai.compute({ module: "finance", function: "npv", args: [0.1, cashflows] }); } catch (error) { if (error instanceof SqaiError) { console.error(error.code, error.source, error.retryable, error.requestId); // → "seed_required" "sqai" false null if (error.retryable) { // safe to retry (compute_runtime_unavailable, rate_limited, …) } } } ``` {% endtab %} {% tab title="Python" icon="python" %} ```python from sqai import SqaiError try: client.compute(module="finance", function="npv", args=[0.1, cashflows]) except SqaiError as error: print(error.code, error.source, error.retryable, error.request_id) # → seed_required sqai False None if error.retryable: ... # safe to retry ``` {% endtab %} {% endtabs %} ## Is the runtime warm? `latency_ms` on any `compute()` result is the tell: warm calls are sub-millisecond (`finance.npv` \~0.93ms). A \~110s first call is the one-time provision, not a per-query cost — the runtime stays resident. See [Determinism & provenance](/concepts/determinism.md) for the full result envelope. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sqai.com/reference/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.