generated: '2026-08-19' method: searched source: https://docs.abloatai.com/errors note: 'Ablo publishes a canonical, generated error registry — every code below is a documented, stable machine identifier whose anchor is the target of the doc_url the API itself returns in the error body. Retryability is the provider''s own published flag. This is a registry, not RFC 9457: the envelope is a custom AbloError JSON object, not application/problem+json.' format: custom-envelope rfc9457: false contract_version: '2026-08-15' contract_version_header: Ablo-Version envelope: schema: openapi/abloatai-api-openapi.yml#/components/schemas/ErrorEnvelope media_type: application/json fields: - field: type required: true meaning: Coarse error class — catch with instanceof or switch on it (AbloValidationError, AbloAuthenticationError, AbloClaimedError, AbloRateLimitError, AbloStaleContextError). - field: code required: false meaning: Stable machine identifier; the key of this catalog. - field: message required: true meaning: Human-readable explanation. - field: doc_url required: false meaning: Deep link to this code's anchor in the published registry. - field: request_id required: false meaning: Correlates to Ablo server logs; also on the X-Request-Id response header. - field: event_id required: false meaning: Event correlation id. - field: param required: false meaning: The offending parameter, when the error is field-scoped. - field: errors required: false meaning: Array of per-field {code,message,param} for multi-field validation failures. observed_example: type: AbloAuthenticationError code: auth_no_credentials message: no recognized authentication credential was presented probed: https://api.abloatai.com/api/v1/schema http_status: 401 note: Also echoed on the X-Auth-Failure response header, which is CORS-exposed. retryability: Published per code. Transient transport and lease failures are retryable; validation and permission errors are not. Retryable means the SAME request can succeed later without changing anything. categories: - name: Authentication description: Missing, invalid, revoked, or expired credentials. Re-authenticate. - name: Permission description: Credentials were valid but the action is forbidden for this caller. - name: Capability description: The connection's resolved scope does not cover the attempted action. - name: Claim contention description: The target is held by another participant, or a claim lease could not be acquired. Usually retryable once the holder releases. - name: Conflict description: The write collided with concurrent state (stale read, idempotency mismatch, incompatible change). - name: Validation description: The request payload or parameters were invalid. Fix the input and retry. - name: Not found description: The referenced resource does not exist (or is hidden by scope). - name: Tenant / schema resolution description: The named model could not be resolved in the tenant schema. - name: Schema description: Schema declaration or migration problems. - name: Bootstrap description: Initial snapshot fetch problems. - name: Transport description: Network, connection, queue, and timeout failures. Generally retryable. - name: Rate limit description: Too many requests. Back off before retrying. - name: Server description: Server-side failures. Generally retryable with backoff. - name: Client (SDK) invariants description: Local SDK usage errors — never sent over the network. No HTTP status. counts: codes: 288 categories: 14 retryable: 43 not_retryable: 171 client_only: 74 unclassified: 0 http_status_distribution: '400': 79 '401': 24 '403': 25 '404': 8 '409': 20 '413': 2 '422': 1 '426': 1 '429': 3 '500': 13 '502': 8 '503': 23 '504': 7 client-only: 74 problems: - code: api_key_required category: Authentication transport: http retryable: false message: 'This operation requires an API key, and none was presented. Send one as `Authorization: Bearer `.' doc_url: https://docs.abloatai.com/errors#api_key_required http_status: 401 - code: apikey_expired category: Authentication transport: http retryable: false message: This ephemeral API key has expired. Mint a fresh key from your still-valid session and retry the request. doc_url: https://docs.abloatai.com/errors#apikey_expired http_status: 401 - code: apikey_invalid category: Authentication transport: http retryable: false message: This API key isn't one Ablo recognizes — it may be mistyped, truncated, or belong to a different environment. Check the key and try again. doc_url: https://docs.abloatai.com/errors#apikey_invalid http_status: 401 - code: apikey_missing category: Authentication transport: http retryable: false message: 'The request arrived without an API key. Send one as `Authorization: Bearer `.' doc_url: https://docs.abloatai.com/errors#apikey_missing http_status: 401 - code: apikey_revoked category: Authentication transport: http retryable: false message: This API key has been revoked and can no longer be used. Mint a new key from the dashboard. doc_url: https://docs.abloatai.com/errors#apikey_revoked http_status: 401 - code: auth_no_credentials category: Authentication transport: http retryable: false message: 'No recognized authentication credential was presented — no API key and no bearer JWT. Send `Authorization: Bearer `.' doc_url: https://docs.abloatai.com/errors#auth_no_credentials http_status: 401 - code: better_auth_request_failed category: Authentication transport: http retryable: false message: The authentication request was rejected. Check the submitted credentials or request and try again. doc_url: https://docs.abloatai.com/errors#better_auth_request_failed http_status: 400 - code: browser_apikey_blocked category: Authentication transport: client-only retryable: null message: A raw API key was used from a browser, where anyone can read it. Keep secret keys server-side and hand the browser a short-lived ephemeral key instead. doc_url: https://docs.abloatai.com/errors#browser_apikey_blocked - code: capability_id_missing category: Authentication transport: http retryable: false message: This request must name a capability id, but none was provided. doc_url: https://docs.abloatai.com/errors#capability_id_missing http_status: 401 - code: capability_required category: Authentication transport: http retryable: false message: This operation requires a capability, and none was presented. doc_url: https://docs.abloatai.com/errors#capability_required http_status: 401 - code: cli_api_key_missing category: Authentication transport: client-only retryable: null message: The command needs an API key and none was found on this machine. Run `ablo login` (or set ABLO_API_KEY), then re-run the command. doc_url: https://docs.abloatai.com/errors#cli_api_key_missing - code: exchange_failed category: Authentication transport: http retryable: false message: The API key could not be exchanged for a working credential — the exchange was rejected. Check that the key is still valid. doc_url: https://docs.abloatai.com/errors#exchange_failed http_status: 401 - code: file_upload_auth_required category: Authentication transport: http retryable: false message: File uploads require an authenticated session. Sign in and retry. doc_url: https://docs.abloatai.com/errors#file_upload_auth_required http_status: 401 - code: identity_missing_organization category: Authentication transport: http retryable: false message: Authentication succeeded, but the credential resolves to no organization, so requests cannot be scoped. Check that the key or token carries an organization. doc_url: https://docs.abloatai.com/errors#identity_missing_organization http_status: 401 - code: identity_resolve_failed category: Authentication transport: http retryable: false message: The server could not resolve an identity for this credential — the identity lookup was rejected. Check that the credential is still valid. doc_url: https://docs.abloatai.com/errors#identity_resolve_failed http_status: 401 - code: jwt_audience_mismatch category: Authentication transport: http retryable: false message: The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with. doc_url: https://docs.abloatai.com/errors#jwt_audience_mismatch http_status: 401 - code: jwt_expired category: Authentication transport: http retryable: false message: The bearer JWT has expired. Obtain a fresh token from your identity provider and retry. doc_url: https://docs.abloatai.com/errors#jwt_expired http_status: 401 - code: jwt_invalid category: Authentication transport: http retryable: false message: The bearer JWT failed validation for a reason the server could not classify further. Check the token's issuer, signature, audience, and expiry. doc_url: https://docs.abloatai.com/errors#jwt_invalid http_status: 401 - code: jwt_issuer_untrusted category: Authentication transport: http retryable: false message: The bearer JWT's `iss` is not a registered trusted issuer. Check the token's issuer claim, or register the issuer with your deployment before retrying. doc_url: https://docs.abloatai.com/errors#jwt_issuer_untrusted http_status: 401 - code: jwt_malformed category: Authentication transport: http retryable: false message: The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent. doc_url: https://docs.abloatai.com/errors#jwt_malformed http_status: 401 - code: jwt_missing_issuer category: Authentication transport: http retryable: false message: The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer. doc_url: https://docs.abloatai.com/errors#jwt_missing_issuer http_status: 401 - code: jwt_missing_organization category: Authentication transport: http retryable: false message: The bearer JWT carries no organization context — neither a fixed org for the issuer nor the configured organization claim. doc_url: https://docs.abloatai.com/errors#jwt_missing_organization http_status: 401 - code: jwt_missing_subject category: Authentication transport: http retryable: false message: The bearer JWT has no `sub` (subject) claim to identify the user. doc_url: https://docs.abloatai.com/errors#jwt_missing_subject http_status: 401 - code: jwt_org_membership_denied category: Authentication transport: http retryable: false message: The bearer JWT's subject is not an active member of the organization in its `org_id` claim (removed, suspended, or the claim does not match a membership). doc_url: https://docs.abloatai.com/errors#jwt_org_membership_denied http_status: 403 - code: jwt_signature_invalid category: Authentication transport: http retryable: false message: The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token). doc_url: https://docs.abloatai.com/errors#jwt_signature_invalid http_status: 401 - code: session_expired category: Authentication transport: http retryable: false message: Your session has expired or is no longer valid. Sign in again to continue. doc_url: https://docs.abloatai.com/errors#session_expired http_status: 401 - code: source_api_key_unresolved category: Authentication transport: http retryable: false message: The API key presented for this data source could not be resolved to a known key. Check the key and its environment. doc_url: https://docs.abloatai.com/errors#source_api_key_unresolved http_status: 401 - code: source_connector_unauthenticated category: Authentication transport: http retryable: false message: The localhost Data Source connector could not authenticate. Rerun `ablo dev --local` so it mints and uses a fresh branch-bound secret key. doc_url: https://docs.abloatai.com/errors#source_connector_unauthenticated http_status: 401 - code: unknown_auth_host category: Authentication transport: http retryable: false message: The authentication host is not recognized. doc_url: https://docs.abloatai.com/errors#unknown_auth_host http_status: 400 - code: branch_scope_denied category: Permission transport: http retryable: false message: The request targeted a branch the caller's key is not scoped to. doc_url: https://docs.abloatai.com/errors#branch_scope_denied http_status: 403 - code: byo_host_not_allowed category: Permission transport: http retryable: false message: The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used. doc_url: https://docs.abloatai.com/errors#byo_host_not_allowed http_status: 403 - code: byo_role_cannot_enforce_rls category: Permission transport: http retryable: false message: The direct Postgres connector role cannot enforce row-level security. doc_url: https://docs.abloatai.com/errors#byo_role_cannot_enforce_rls http_status: 403 - code: byo_role_unreadable category: Permission transport: http retryable: false message: The direct Postgres connector role could not be introspected. doc_url: https://docs.abloatai.com/errors#byo_role_unreadable http_status: 403 - code: byo_tenant_tables_unforced_rls category: Permission transport: http retryable: false message: Tenant tables do not have RLS forced under the direct Postgres connector role. doc_url: https://docs.abloatai.com/errors#byo_tenant_tables_unforced_rls http_status: 403 - code: database_host_not_allowed category: Permission transport: http retryable: false message: The database host did not resolve exclusively to an allowed address for this route. Use a publicly resolvable direct endpoint, or configure the matching PrivateLink, peering, or VPN route. Localhost has its own `database_loopback_requires_connector` workflow. doc_url: https://docs.abloatai.com/errors#database_host_not_allowed http_status: 403 - code: database_role_cannot_enforce_rls category: Permission transport: http retryable: false message: The database role Ablo connects with is a superuser or has `BYPASSRLS`, so Postgres will not enforce row-level security for it. Connect with a role that is subject to RLS. doc_url: https://docs.abloatai.com/errors#database_role_cannot_enforce_rls http_status: 403 - code: database_role_unreadable category: Permission transport: http retryable: false message: Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced. doc_url: https://docs.abloatai.com/errors#database_role_unreadable http_status: 403 - code: database_tables_unforced_rls category: Permission transport: http retryable: false message: Some synced tables do not have `FORCE ROW LEVEL SECURITY` applied, so the table owner can bypass row isolation. Run `ALTER TABLE ... FORCE ROW LEVEL SECURITY` on each synced table. doc_url: https://docs.abloatai.com/errors#database_tables_unforced_rls http_status: 403 - code: forbidden category: Permission transport: http retryable: false message: The caller lacks permission for this operation. doc_url: https://docs.abloatai.com/errors#forbidden http_status: 403 - code: issuer_register_forbidden category: Permission transport: http retryable: false message: Registering a trusted issuer requires a secret (`sk_`) API key. The key presented is not a secret key. doc_url: https://docs.abloatai.com/errors#issuer_register_forbidden http_status: 403 - code: organization_disabled category: Permission transport: http retryable: false message: This organization has been disabled by an operator. Contact support before retrying. doc_url: https://docs.abloatai.com/errors#organization_disabled http_status: 403 - code: organization_mismatch category: Permission transport: http retryable: false message: The request targeted an organization the caller is not scoped to. doc_url: https://docs.abloatai.com/errors#organization_mismatch http_status: 403 - code: permission_denied category: Permission transport: http retryable: false message: The participant is not allowed to execute this mutator. doc_url: https://docs.abloatai.com/errors#permission_denied http_status: 403 - code: project_scope_denied category: Permission transport: http retryable: false message: The request targeted a project the caller's key is not scoped to. doc_url: https://docs.abloatai.com/errors#project_scope_denied http_status: 403 - code: schema_provisioning_forbidden category: Permission transport: http retryable: false message: 'Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.' doc_url: https://docs.abloatai.com/errors#schema_provisioning_forbidden http_status: 403 - code: server_side_only category: Permission transport: http retryable: false message: This endpoint is available only to trusted server-side callers. doc_url: https://docs.abloatai.com/errors#server_side_only http_status: 403 - code: source_connector_production_not_enabled category: Permission transport: http retryable: false message: This production Data Source has not opted into reverse-channel transport. `ablo dev --local` is for child branches; use a direct production endpoint or explicitly enable the supported production reverse-channel route. doc_url: https://docs.abloatai.com/errors#source_connector_production_not_enabled http_status: 403 - code: source_connector_requires_secret_key category: Permission transport: http retryable: false message: A Data Source reverse channel must authenticate with the branch-bound secret (`sk_`) key created by `ablo dev`; browser, ephemeral, restricted, and management keys cannot serve a database. doc_url: https://docs.abloatai.com/errors#source_connector_requires_secret_key http_status: 403 - code: wide_scope_forbidden category: Permission transport: http retryable: false message: This caller may not use a wide scope. Request a scope narrowed to the resources you need. doc_url: https://docs.abloatai.com/errors#wide_scope_forbidden http_status: 403 - code: capability_invalid category: Capability transport: http retryable: false message: This capability cannot be used — it is unknown, revoked, or expired. Request a fresh grant. doc_url: https://docs.abloatai.com/errors#capability_invalid http_status: 403 - code: capability_scope_denied category: Capability transport: http retryable: false message: This action falls outside the scope granted to the connection, so it was denied. doc_url: https://docs.abloatai.com/errors#capability_scope_denied http_status: 403 - code: claim_conflict category: Claim contention transport: http retryable: false message: Another participant holds a claim on this row, so the write was rejected. Take a claim with `ablo..claim` to queue fairly behind the holder, or re-read and rebase. doc_url: https://docs.abloatai.com/errors#claim_conflict http_status: 409 - code: claim_lease_unavailable category: Claim contention transport: http retryable: true message: The claim-lease coordination subsystem is temporarily unavailable, so the claim could not be processed. Retry shortly. doc_url: https://docs.abloatai.com/errors#claim_lease_unavailable http_status: 503 - code: claim_lost category: Claim contention transport: http retryable: false message: The claim held on this row was lost before the write could apply. Re-acquire with `ablo..claim` and retry from its fresh snapshot. doc_url: https://docs.abloatai.com/errors#claim_lost http_status: 409 - code: claim_not_wired category: Claim contention transport: client-only retryable: null message: Claims were used, but this runtime has no claim support wired in. The standard `Ablo({ schema, apiKey })` client wires it up automatically. doc_url: https://docs.abloatai.com/errors#claim_not_wired - code: claim_queued category: Claim contention transport: http retryable: true message: The claim was queued behind the current lease holder and will be granted in turn. Poll `claims.retrieve({ claimId })` for the grant — the id rides on the error — or read `claim.queue` to see the line. doc_url: https://docs.abloatai.com/errors#claim_queued http_status: 409 - code: claim_wait_aborted category: Claim contention transport: http retryable: true message: The wait for this claim lease was aborted before the lease was granted. doc_url: https://docs.abloatai.com/errors#claim_wait_aborted http_status: 409 - code: entity_claimed category: Claim contention transport: http retryable: false message: This row is currently claimed by another participant, so the write was blocked. Queue behind the holder with `ablo..claim`, or wait for the claim to clear. doc_url: https://docs.abloatai.com/errors#entity_claimed http_status: 409 - code: fence_token_stale category: Claim contention transport: http retryable: false message: This claim is no longer current because another participant completed newer work on the row. Re-claim the row and retry from the fresh state. doc_url: https://docs.abloatai.com/errors#fence_token_stale http_status: 409 - code: grant_timeout category: Claim contention transport: http retryable: true message: The wait for the claim grant timed out before your turn arrived (`waitTimeoutMs`). Claim again to rejoin the line, raise the cap, or re-read and proceed without the claim. doc_url: https://docs.abloatai.com/errors#grant_timeout http_status: 504 - code: model_claim_not_configured category: Claim contention transport: client-only retryable: null message: Claiming is unavailable on this model client. Construct it through the standard Ablo({ schema, apiKey }) client and retry. doc_url: https://docs.abloatai.com/errors#model_claim_not_configured - code: model_claimed category: Claim contention transport: http retryable: false message: Another participant holds a claim on this row. Read `claim.state` to see who holds it, or queue behind them with a claim of your own. doc_url: https://docs.abloatai.com/errors#model_claimed http_status: 409 - code: model_claimed_timeout category: Claim contention transport: http retryable: false message: Another participant held a claim on this row and did not release it in time. Retry, or read `claim.state` to see who holds it. doc_url: https://docs.abloatai.com/errors#model_claimed_timeout http_status: 409 - code: model_join_not_configured category: Claim contention transport: client-only retryable: null message: join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport). doc_url: https://docs.abloatai.com/errors#model_join_not_configured - code: contention_exhausted category: Conflict transport: client-only retryable: null message: A functional update kept losing to concurrent writes and exhausted its reconcile budget. Back off and retry, raise `retries`, or move the row to the WebSocket transport. doc_url: https://docs.abloatai.com/errors#contention_exhausted - code: database_already_connected category: Conflict transport: http retryable: false message: This database is already connected to another environment in your organization. Ablo streams a database from one environment at a time, so connecting it to a second one would leave the two reading the same change stream, and the newer connection would take the stream over from the older. Give this environment a database of its own — on a branching provider a branch of the same database is the usual answer, and it is what sandbox is for. If you meant to move the connection rather than add one, disconnect it from the environment that holds it with `ablo connect deregister` first. doc_url: https://docs.abloatai.com/errors#database_already_connected http_status: 409 - code: foreign_key_violation category: Conflict transport: http retryable: false message: 'The database rejected the write on a foreign-key constraint: a referenced row does not exist, or the row being deleted is still referenced by others. The error details name the constraint.' doc_url: https://docs.abloatai.com/errors#foreign_key_violation http_status: 409 - code: idempotency_conflict category: Conflict transport: http retryable: false message: This `Idempotency-Key` was already used with a different request body. Reuse a key only to retry an identical request; otherwise generate a new one. doc_url: https://docs.abloatai.com/errors#idempotency_conflict http_status: 409 - code: idempotency_key_expired category: Conflict transport: http retryable: false message: This idempotency key belongs to an expired retained source intent and cannot be executed again safely. Use a new key only for a genuinely new write. doc_url: https://docs.abloatai.com/errors#idempotency_key_expired http_status: 409 - code: incompatible_change category: Conflict transport: http retryable: false message: The schema change is incompatible with the schema currently deployed and cannot be applied as-is. doc_url: https://docs.abloatai.com/errors#incompatible_change http_status: 409 - code: precondition_failed category: Conflict transport: http retryable: false message: A conditional operation did not match the current database row. The complete atomic commit was rejected and no operation in the batch was applied. doc_url: https://docs.abloatai.com/errors#precondition_failed http_status: 409 - code: replication_reset_required category: Conflict transport: http retryable: false message: This branch has live replicated rows for a mapped model that disappeared. Declare a rename or an explicit drop/reset before advancing the schema. doc_url: https://docs.abloatai.com/errors#replication_reset_required http_status: 409 - code: source_transport_pinned category: Conflict transport: http retryable: false message: An earlier attempt under this idempotency key was pinned to a different source transport. Restore that route and retry the same key; Ablo will not switch a possibly committed write. doc_url: https://docs.abloatai.com/errors#source_transport_pinned http_status: 409 - code: stale_context category: Conflict transport: http retryable: false message: The row changed after you read it — the write's `readAt` watermark is older than the current row version. Pass a function to `update(id, current => next)` and the SDK re-reads and retries for you; or re-read and retry by hand. doc_url: https://docs.abloatai.com/errors#stale_context http_status: 409 - code: unique_violation category: Conflict transport: http retryable: false message: The write duplicates a value that must be unique — another row already holds it. Choose a different value, or update the existing row. doc_url: https://docs.abloatai.com/errors#unique_violation http_status: 409 - code: update_aborted category: Conflict transport: client-only retryable: null message: The functional update was aborted via its `AbortSignal` before the write landed; nothing was written. doc_url: https://docs.abloatai.com/errors#update_aborted - code: agent_perception_missing_context category: Validation transport: http retryable: false message: The agent perception request is missing context it needs to run. Include the required context fields and retry. doc_url: https://docs.abloatai.com/errors#agent_perception_missing_context http_status: 422 - code: capability_id_required category: Validation transport: http retryable: false message: A capability id is required for this request. doc_url: https://docs.abloatai.com/errors#capability_id_required http_status: 400 - code: check_violation category: Validation transport: http retryable: false message: The database rejected a value that fails one of its check constraints. The error details name the constraint; adjust the value and retry. doc_url: https://docs.abloatai.com/errors#check_violation http_status: 400 - code: claim_id_required category: Validation transport: http retryable: false message: A claim id is required for this request. doc_url: https://docs.abloatai.com/errors#claim_id_required http_status: 400 - code: cli_database_url_missing category: Validation transport: client-only retryable: null message: The command needs a database connection string and none was found — no DATABASE_URL in the process environment, .env.local, or .env, and no --url flag. doc_url: https://docs.abloatai.com/errors#cli_database_url_missing - code: cli_invalid_arguments category: Validation transport: client-only retryable: null message: The CLI was invoked with an unknown flag or a malformed flag value. doc_url: https://docs.abloatai.com/errors#cli_invalid_arguments - code: column_type_mismatch category: Validation transport: http retryable: false message: A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) — but a scalar column (integer, boolean, uuid, timestamp, …) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema. doc_url: https://docs.abloatai.com/errors#column_type_mismatch http_status: 400 - code: column_value_out_of_range category: Validation transport: http retryable: false message: A stored value is outside the range the field was declared to hold. A number field reads back as a JavaScript number, which represents integers exactly only up to 9,007,199,254,740,991; a bigint column holding more than that would come back rounded. Declare the field as text to read those values digit for digit. doc_url: https://docs.abloatai.com/errors#column_value_out_of_range http_status: 400 - code: commit_operation_action_required category: Validation transport: http retryable: false message: A commit operation is missing its `action`. doc_url: https://docs.abloatai.com/errors#commit_operation_action_required http_status: 400 - code: commit_operation_invalid category: Validation transport: http retryable: false message: A commit operation failed validation against the wire commit-operation schema — wrong field type (e.g. a string `readAt`), unknown `type`, or missing `model`. The whole batch was rejected; the error names the offending operation index and field path. doc_url: https://docs.abloatai.com/errors#commit_operation_invalid http_status: 400 - code: commit_operation_model_required category: Validation transport: http retryable: false message: A commit operation is missing its `model`. doc_url: https://docs.abloatai.com/errors#commit_operation_model_required http_status: 400 - code: commit_operation_required category: Validation transport: http retryable: false message: A commit must carry `operation` or `operations`. doc_url: https://docs.abloatai.com/errors#commit_operation_required http_status: 400 - code: commit_operation_unsupported category: Validation transport: http retryable: false message: A commit operation used an unsupported `action`. doc_url: https://docs.abloatai.com/errors#commit_operation_unsupported http_status: 400 - code: commit_operations_ambiguous category: Validation transport: http retryable: false message: A commit supplied both `operation` and `operations`. Send one or the other, not both. doc_url: https://docs.abloatai.com/errors#commit_operations_ambiguous http_status: 400 - code: commit_too_many_operations category: Validation transport: http retryable: false message: A commit exceeded the per-commit operation limit; split it into smaller batches. doc_url: https://docs.abloatai.com/errors#commit_too_many_operations http_status: 400 - code: constraint_violation category: Validation transport: http retryable: false message: The database rejected the write on an integrity constraint. The error details identify the specific constraint. doc_url: https://docs.abloatai.com/errors#constraint_violation http_status: 400 - code: data_session_unsupported category: Validation transport: http retryable: false message: This sign-in host cannot create the requested data session. doc_url: https://docs.abloatai.com/errors#data_session_unsupported http_status: 400 - code: database_loopback_requires_connector category: Validation transport: http retryable: false message: Ablo Cloud cannot open a direct PostgreSQL connection to localhost on your machine. For localhost-first development, run `ablo migrate` once and keep `ablo dev --local` running; use a network-reachable direct route only when Ablo must observe arbitrary SQL writes through WAL. doc_url: https://docs.abloatai.com/errors#database_loopback_requires_connector http_status: 400 - code: database_not_replication_ready category: Validation transport: http retryable: false message: This database is not set up for logical replication yet. Every failing item — wal_level, the publication, the replication grant, a replica identity — is listed in the error details with its exact fix. `ablo connect` prints the one-time setup; `ablo connect check` verifies it. doc_url: https://docs.abloatai.com/errors#database_not_replication_ready http_status: 400 - code: database_unreachable category: Validation transport: http retryable: false message: Ablo could not reach this database to check that it can stream replication. The connection string may be wrong, the host may not be reachable from Ablo's servers, or the credentials may not be accepted. doc_url: https://docs.abloatai.com/errors#database_unreachable http_status: 400 - code: datasource_connection_unsupported category: Validation transport: http retryable: false message: This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead. doc_url: https://docs.abloatai.com/errors#datasource_connection_unsupported http_status: 400 - code: duration_invalid category: Validation transport: client-only retryable: null message: A duration value was not a number of seconds or a "500ms" | "30s" | "3m" | "24h" string. doc_url: https://docs.abloatai.com/errors#duration_invalid - code: events_required category: Validation transport: http retryable: false message: The request must include a non-empty `events` array. doc_url: https://docs.abloatai.com/errors#events_required http_status: 400 - code: idempotency_key_too_long category: Validation transport: http retryable: false message: The supplied `Idempotency-Key` exceeds the maximum length. Use a shorter key — a UUID works well. doc_url: https://docs.abloatai.com/errors#idempotency_key_too_long http_status: 400 - code: ingest_failed category: Validation transport: http retryable: false message: The source-event batch was rejected during ingest and nothing was appended. Check the events against the expected shape and re-send. doc_url: https://docs.abloatai.com/errors#ingest_failed http_status: 400 - code: invalid_body category: Validation transport: http retryable: false message: The request body was missing, unparseable, or the wrong shape. doc_url: https://docs.abloatai.com/errors#invalid_body http_status: 400 - code: invalid_id category: Validation transport: http retryable: false message: The id in the request is not a valid identifier. doc_url: https://docs.abloatai.com/errors#invalid_id http_status: 400 - code: invalid_input category: Validation transport: http retryable: false message: The mutator input could not be parsed or failed input validation. doc_url: https://docs.abloatai.com/errors#invalid_input http_status: 400 - code: invalid_json category: Validation transport: http retryable: false message: The request body was not valid JSON. doc_url: https://docs.abloatai.com/errors#invalid_json http_status: 400 - code: invalid_model category: Validation transport: http retryable: false message: The model name in the request is not a valid model identifier. doc_url: https://docs.abloatai.com/errors#invalid_model http_status: 400 - code: invalid_participant_kind category: Validation transport: http retryable: false message: The participant kind is not one the server recognizes. doc_url: https://docs.abloatai.com/errors#invalid_participant_kind http_status: 400 - code: invalid_request category: Validation transport: http retryable: false message: The request parameters were invalid. doc_url: https://docs.abloatai.com/errors#invalid_request http_status: 400 - code: invalid_schema category: Validation transport: http retryable: false message: The submitted schema could not be parsed. doc_url: https://docs.abloatai.com/errors#invalid_schema http_status: 400 - code: invalid_sync_group category: Validation transport: http retryable: false message: Sync groups must be `default` or `:`. doc_url: https://docs.abloatai.com/errors#invalid_sync_group http_status: 400 - code: item_id_required category: Validation transport: http retryable: false message: An item id is required for this request. doc_url: https://docs.abloatai.com/errors#item_id_required http_status: 400 - code: malformed_claim category: Validation transport: http retryable: false message: The claim payload could not be parsed. A claim on a row must name the model and the entity it targets; a claim on a scope, which is what `join` opens, must name sync groups spelled `kind:id` or `default`. Check the payload shape and resend. doc_url: https://docs.abloatai.com/errors#malformed_claim http_status: 400 - code: malformed_subscription category: Validation transport: http retryable: false message: 'The `update_subscription` payload was malformed; expected `{ syncGroups: string[] }`.' doc_url: https://docs.abloatai.com/errors#malformed_subscription http_status: 400 - code: mesh_message_from_id_spoof category: Validation transport: http retryable: false message: The mesh message's `from` id does not match the authenticated sender, so it was rejected — participants may only send as themselves. doc_url: https://docs.abloatai.com/errors#mesh_message_from_id_spoof http_status: 403 - code: mesh_message_from_kind_mismatch category: Validation transport: http retryable: false message: The mesh message's `from` kind does not match the kind of the authenticated sender, so it was rejected. doc_url: https://docs.abloatai.com/errors#mesh_message_from_kind_mismatch http_status: 403 - code: mesh_message_invalid_input category: Validation transport: http retryable: false message: The mesh message payload failed input validation and was not delivered. doc_url: https://docs.abloatai.com/errors#mesh_message_invalid_input http_status: 400 - code: model_identifier_missing category: Validation transport: http retryable: false message: The payload is missing the model's identifier, so the target row cannot be determined. Include the `id` field. doc_url: https://docs.abloatai.com/errors#model_identifier_missing http_status: 400 - code: model_query_failed category: Validation transport: http retryable: false message: The model query failed to execute. Check the query filters and operators. doc_url: https://docs.abloatai.com/errors#model_query_failed http_status: 400 - code: model_required_field_missing category: Validation transport: http retryable: false message: The write is missing a field the model marks as required. Include the field and retry. doc_url: https://docs.abloatai.com/errors#model_required_field_missing http_status: 400 - code: narrow_scope_required category: Validation transport: http retryable: false message: This request requires a scope narrowed to specific resources; the presented scope is too broad. doc_url: https://docs.abloatai.com/errors#narrow_scope_required http_status: 400 - code: not_null_violation category: Validation transport: http retryable: false message: The database rejected the write because a required column was left empty — a not-null constraint. The error details name the column; supply a value and retry. doc_url: https://docs.abloatai.com/errors#not_null_violation http_status: 400 - code: org_id_required category: Validation transport: http retryable: false message: An organization id is required for this request. doc_url: https://docs.abloatai.com/errors#org_id_required http_status: 400 - code: position_missing_parent category: Validation transport: http retryable: false message: This row gives a position but not the parent it belongs to, so the position cannot be resolved. Send the parent id alongside the position. doc_url: https://docs.abloatai.com/errors#position_missing_parent http_status: 400 - code: position_unknown_sibling category: Validation transport: http retryable: false message: This row is positioned relative to another row that is not in the same parent. Check that the neighbouring row id is correct and still present. doc_url: https://docs.abloatai.com/errors#position_unknown_sibling http_status: 400 - code: presence_identity_required category: Validation transport: http retryable: false message: Presence requests must carry both `userId` and `organizationId`. doc_url: https://docs.abloatai.com/errors#presence_identity_required http_status: 400 - code: project_slug_taken category: Validation transport: http retryable: false message: A project with this slug already exists in the organization. Choose a different slug. doc_url: https://docs.abloatai.com/errors#project_slug_taken http_status: 409 - code: queries_required category: Validation transport: http retryable: false message: The request must include a non-empty `queries` array. doc_url: https://docs.abloatai.com/errors#queries_required http_status: 400 - code: query_invalid_boolean category: Validation transport: http retryable: false message: The query compared a boolean column against an invalid boolean literal. doc_url: https://docs.abloatai.com/errors#query_invalid_boolean http_status: 400 - code: query_invalid_identifier category: Validation transport: http retryable: false message: The query contained an invalid identifier. doc_url: https://docs.abloatai.com/errors#query_invalid_identifier http_status: 400 - code: query_invalid_like_pattern category: Validation transport: http retryable: false message: The `LIKE` pattern must not end with an escape character. doc_url: https://docs.abloatai.com/errors#query_invalid_like_pattern http_status: 400 - code: query_relation_expansion_too_large category: Validation transport: http retryable: false message: A requested relation expansion exceeds the bounded nested-row budget. Query the related model as its own paginated collection instead. doc_url: https://docs.abloatai.com/errors#query_relation_expansion_too_large http_status: 400 - code: query_unknown_relation category: Validation transport: http retryable: false message: The query references a relation the model does not define. Check the relation name against the schema. doc_url: https://docs.abloatai.com/errors#query_unknown_relation http_status: 400 - code: query_unsupported_operator category: Validation transport: http retryable: false message: The query used an unsupported operator. doc_url: https://docs.abloatai.com/errors#query_unsupported_operator http_status: 400 - code: replication_publication_drift category: Validation transport: http retryable: false message: Your schema maps to tables that are not members of the replication publication, so their changes silently never stream and the source looks frozen. The missing tables and the exact `ALTER PUBLICATION … ADD TABLE …` to add them are in the error details — Ablo never alters your database for you. doc_url: https://docs.abloatai.com/errors#replication_publication_drift http_status: 400 - code: request_too_large category: Validation transport: http retryable: false message: The request body exceeds the maximum size. doc_url: https://docs.abloatai.com/errors#request_too_large http_status: 413 - code: schema_definition_invalid category: Validation transport: client-only retryable: null message: A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version). doc_url: https://docs.abloatai.com/errors#schema_definition_invalid - code: schema_too_large category: Validation transport: http retryable: false message: The submitted schema exceeds the maximum size. doc_url: https://docs.abloatai.com/errors#schema_too_large http_status: 413 - code: snapshot_reserved_key category: Validation transport: http retryable: false message: The snapshot uses a key name that is reserved by the runtime. Rename the key and retry. doc_url: https://docs.abloatai.com/errors#snapshot_reserved_key http_status: 400 - code: source_adapter_misconfigured category: Validation transport: client-only retryable: null message: The data-source ORM adapter could not map a schema model onto the backing client — the client exposes no matching delegate or model. Check that the adapter and schema agree on model names. doc_url: https://docs.abloatai.com/errors#source_adapter_misconfigured - code: source_connector_localhost_required category: Validation transport: http retryable: false message: A connector-only development Data Source must use a localhost descriptor. Use `ablo dev --local`; use the ordinary signed HTTPS endpoint registration for a deployed handler. doc_url: https://docs.abloatai.com/errors#source_connector_localhost_required http_status: 400 - code: source_event_invalid category: Validation transport: http retryable: false message: A data-source event was malformed — missing or invalid id, model, entityId, type, or field value. The whole event batch was rejected and nothing was ingested; fix the offending outbox row and re-send. doc_url: https://docs.abloatai.com/errors#source_event_invalid http_status: 400 - code: source_operation_id_required category: Validation transport: client-only retryable: null message: A data-source operation arrived without the entity `id` it targets. doc_url: https://docs.abloatai.com/errors#source_operation_id_required - code: upload_fields_required category: Validation transport: http retryable: false message: The upload request is missing a required field. doc_url: https://docs.abloatai.com/errors#upload_fields_required http_status: 400 - code: upload_items_required category: Validation transport: http retryable: false message: The request must include a non-empty `items` array. doc_url: https://docs.abloatai.com/errors#upload_items_required http_status: 400 - code: usage_invalid category: Validation transport: http retryable: false message: The usage request was invalid. doc_url: https://docs.abloatai.com/errors#usage_invalid http_status: 400 - code: validation_failed category: Validation transport: http retryable: false message: The mutator rejected the input because it violates a business rule. doc_url: https://docs.abloatai.com/errors#validation_failed http_status: 400 - code: write_options_invalid category: Validation transport: client-only retryable: null message: The write options (`idempotencyKey` / `label` / `wait` / `readAt` / `onStale` / `claim`) failed validation against the write-options schema. doc_url: https://docs.abloatai.com/errors#write_options_invalid - code: write_payload_invalid category: Validation transport: client-only retryable: null message: A write payload contained a value that cannot be represented safely as JSON. Use plain objects, arrays, finite numbers, strings, booleans, null, or valid dates. doc_url: https://docs.abloatai.com/errors#write_payload_invalid - code: capability_not_found category: Not found transport: http retryable: false message: No capability exists with the given id. doc_url: https://docs.abloatai.com/errors#capability_not_found http_status: 404 - code: claim_not_found category: Not found transport: http retryable: false message: No claim of yours exists with the given id. It was released, expired, or belongs to a different branch. doc_url: https://docs.abloatai.com/errors#claim_not_found http_status: 404 - code: entity_not_found category: Not found transport: http retryable: false message: No row exists with the requested id. It may have been deleted, or the id may belong to a different environment. doc_url: https://docs.abloatai.com/errors#entity_not_found http_status: 404 - code: invalid_mutator category: Not found transport: http retryable: false message: The requested mutator is not registered on this server. doc_url: https://docs.abloatai.com/errors#invalid_mutator http_status: 404 - code: model_not_found category: Not found transport: http retryable: false message: No row of this model exists with the requested id. It may have been deleted, or the id may belong to a different environment. doc_url: https://docs.abloatai.com/errors#model_not_found http_status: 404 - code: mutate_update_entity_not_found category: Not found transport: http retryable: false message: The row targeted by this update does not exist — it may have been deleted since you read it. Re-read before retrying. doc_url: https://docs.abloatai.com/errors#mutate_update_entity_not_found http_status: 404 - code: no_data_source_registered category: Not found transport: http retryable: false message: This branch is not connected to your database yet. Run `ablo connect` for a cloud-reachable direct Postgres endpoint, or `ablo dev --local` to register and serve a localhost Data Source, then retry. doc_url: https://docs.abloatai.com/errors#no_data_source_registered http_status: 404 - code: source_connector_no_source_registered category: Not found transport: http retryable: false message: The branch has no endpoint Data Source for this connector to serve. Run `ablo dev --local` with the current CLI, which registers the connector-only source before opening the socket. doc_url: https://docs.abloatai.com/errors#source_connector_no_source_registered http_status: 404 - code: connected_database_unreachable category: Tenant / schema resolution transport: http retryable: false message: 'Ablo could not reach the database connected to this environment: it refused the credentials on file, or did not answer at all. A database often changes after it is connected — a password is rotated, an instance is replaced — while the connection goes on pointing at what used to be there. The error names the host it tried. If the password changed, `ablo connect rotate` re-keys the roles and re-registers them; if the database itself was replaced, `ablo connect apply` sets up the new one and `ablo connect register` hands it over. Run either with a key for this environment.' doc_url: https://docs.abloatai.com/errors#connected_database_unreachable http_status: 503 - code: model_not_provisioned category: Tenant / schema resolution transport: http retryable: false message: This model is in the branch's registered schema, but its table does not exist in the connected database yet. `ablo push` records the model but does not change a customer's database. Apply the table migration in your database, then retry the read. doc_url: https://docs.abloatai.com/errors#model_not_provisioned http_status: 409 - code: model_not_tenant_scoped category: Tenant / schema resolution transport: http retryable: false message: This model is not tenant-scoped, so it cannot be queried through the tenant-scoped read path. doc_url: https://docs.abloatai.com/errors#model_not_tenant_scoped http_status: 400 - code: mutate_create_unknown_model category: Tenant / schema resolution transport: http retryable: false message: Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema. doc_url: https://docs.abloatai.com/errors#mutate_create_unknown_model http_status: 400 - code: no_active_organization category: Tenant / schema resolution transport: http retryable: false message: Select an active organization before continuing. doc_url: https://docs.abloatai.com/errors#no_active_organization http_status: 400 - code: server_execute_unknown_model category: Tenant / schema resolution transport: http retryable: false message: Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models. doc_url: https://docs.abloatai.com/errors#server_execute_unknown_model http_status: 400 - code: source_tenancy_not_enforced category: Tenant / schema resolution transport: http retryable: false message: 'This model gets its tenant identity from the connected Data Source, but that connection is not ready for scoped reads yet. Ablo refused the read to prevent data from crossing tenant boundaries. Connect the branch and retry; for internally logged models, use `by: ''column''` or `by: ''parent''`.' doc_url: https://docs.abloatai.com/errors#source_tenancy_not_enforced http_status: 400 - code: tenant_model_columns_unknown category: Tenant / schema resolution transport: http retryable: false message: The columns for this model could not be resolved in the tenant database, so the operation cannot be mapped onto its table. doc_url: https://docs.abloatai.com/errors#tenant_model_columns_unknown http_status: 400 - code: tenant_model_missing_organization_id category: Tenant / schema resolution transport: http retryable: false message: This model's table has no `organization_id` column, which Ablo requires to isolate rows by organization. Add the column before syncing this model. doc_url: https://docs.abloatai.com/errors#tenant_model_missing_organization_id http_status: 400 - code: unknown_model category: Tenant / schema resolution transport: http retryable: false message: Named a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` — the server keeps its own copy of the schema. doc_url: https://docs.abloatai.com/errors#unknown_model http_status: 400 - code: user_scope_not_enforced category: Tenant / schema resolution transport: http retryable: false message: Rows in this model belong to one person rather than the whole organization, but the current read source does not carry the owner identity needed to enforce that boundary. Ablo returned nothing to prevent one member from seeing another member's private records. Use a read source that preserves owner identity, or a credential that acts for the organization. doc_url: https://docs.abloatai.com/errors#user_scope_not_enforced http_status: 400 - code: drop_field category: Schema transport: client-only retryable: null message: This migration would drop an existing field, destroying the data stored in it. doc_url: https://docs.abloatai.com/errors#drop_field - code: drop_model category: Schema transport: client-only retryable: null message: This migration would drop an entire model and its table, destroying the rows stored in it. doc_url: https://docs.abloatai.com/errors#drop_model - code: enum_value_removed category: Schema transport: client-only retryable: null message: This migration removes an enum value that existing rows may still hold. doc_url: https://docs.abloatai.com/errors#enum_value_removed - code: lossy_recreate category: Schema transport: client-only retryable: null message: This migration can only apply by recreating the table, which would not preserve its existing rows. doc_url: https://docs.abloatai.com/errors#lossy_recreate - code: made_required category: Schema transport: client-only retryable: null message: This migration makes an existing optional field required, which rows without a value for it would violate. doc_url: https://docs.abloatai.com/errors#made_required - code: query_relation_target_unknown category: Schema transport: http retryable: false message: A relation in the query targets a model the schema does not define. doc_url: https://docs.abloatai.com/errors#query_relation_target_unknown http_status: 500 - code: required_field_added category: Schema transport: client-only retryable: null message: This migration adds a new required field that existing rows have no value for. doc_url: https://docs.abloatai.com/errors#required_field_added - code: risky_cast category: Schema transport: client-only retryable: null message: This migration changes a column to a type its current values may not convert to cleanly. doc_url: https://docs.abloatai.com/errors#risky_cast - code: schema_field_consecutive_caps category: Schema transport: http retryable: false message: A schema field name contains consecutive capital letters, which cannot be mapped to a column name unambiguously. Write acronyms in lower case (`apiKey`, not `APIKey`). doc_url: https://docs.abloatai.com/errors#schema_field_consecutive_caps http_status: 400 - code: schema_field_not_camelcase category: Schema transport: http retryable: false message: A schema field name is not camelCase. Rename the field (for example `dueDate`) — Ablo derives column names from camelCase field names. doc_url: https://docs.abloatai.com/errors#schema_field_not_camelcase http_status: 400 - code: schema_grants_identifier_unsafe category: Schema transport: http retryable: false message: A `grants` declaration references an identifier that is not safe to use in SQL. Use plain column and relation names. doc_url: https://docs.abloatai.com/errors#schema_grants_identifier_unsafe http_status: 400 - code: schema_grants_relation_kind category: Schema transport: http retryable: false message: A `grants` declaration references a relation of a kind it cannot traverse. doc_url: https://docs.abloatai.com/errors#schema_grants_relation_kind http_status: 400 - code: schema_grants_relation_missing category: Schema transport: http retryable: false message: A `grants` declaration references a relation the model does not define. Check the relation name against the model. doc_url: https://docs.abloatai.com/errors#schema_grants_relation_missing http_status: 400 - code: schema_grants_shape_invalid category: Schema transport: http retryable: false message: A `grants` declaration in the schema has an invalid shape and could not be parsed. doc_url: https://docs.abloatai.com/errors#schema_grants_shape_invalid http_status: 400 - code: schema_grants_target_not_scope_root category: Schema transport: http retryable: false message: A `grants` declaration targets a model that is not a scope root, so access cannot be derived from it. doc_url: https://docs.abloatai.com/errors#schema_grants_target_not_scope_root http_status: 400 - code: schema_mutable_missing_meta category: Schema transport: http retryable: false message: The schema is declared mutable but is missing its required `meta` block. doc_url: https://docs.abloatai.com/errors#schema_mutable_missing_meta http_status: 400 - code: schema_reserved_field category: Schema transport: client-only retryable: null message: A model declared `id`, the one universal field Ablo supplies. Remove it from the declared application fields. doc_url: https://docs.abloatai.com/errors#schema_reserved_field - code: schema_scope_invalid category: Schema transport: http retryable: false message: The model's scope predicate could not be built. doc_url: https://docs.abloatai.com/errors#schema_scope_invalid http_status: 500 - code: schema_scope_kind_invalid category: Schema transport: http retryable: false message: A scope declaration in the schema uses a kind the engine does not recognize. doc_url: https://docs.abloatai.com/errors#schema_scope_kind_invalid http_status: 400 - code: schema_table_invalid category: Schema transport: http retryable: false message: The model's table identifier is invalid. doc_url: https://docs.abloatai.com/errors#schema_table_invalid http_status: 500 - code: bootstrap_cancelled category: Bootstrap transport: client-only retryable: null message: This bootstrap request was cancelled before it finished, because a newer one replaced it or the bootstrap it belonged to had already failed. It is not retried on its own. doc_url: https://docs.abloatai.com/errors#bootstrap_cancelled - code: bootstrap_fetch_timeout category: Bootstrap transport: http retryable: true message: The initial bootstrap fetch timed out before the server responded. Retry shortly. doc_url: https://docs.abloatai.com/errors#bootstrap_fetch_timeout http_status: 504 - code: bootstrap_offline category: Bootstrap transport: http retryable: true message: Bootstrap could not run because the client is offline. It can proceed once the network returns. doc_url: https://docs.abloatai.com/errors#bootstrap_offline http_status: 503 - code: bootstrap_offline_no_cache category: Bootstrap transport: http retryable: false message: The client is offline and no cached snapshot is available to start from, so there is no data to load until the network returns. doc_url: https://docs.abloatai.com/errors#bootstrap_offline_no_cache http_status: 503 - code: bootstrap_response_invalid category: Bootstrap transport: http retryable: true message: The bootstrap response could not be parsed. Retrying may succeed. doc_url: https://docs.abloatai.com/errors#bootstrap_response_invalid http_status: 502 - code: bootstrap_response_schema_invalid category: Bootstrap transport: http retryable: true message: The bootstrap response parsed but failed schema validation, so it was not applied. Retrying may succeed. doc_url: https://docs.abloatai.com/errors#bootstrap_response_schema_invalid http_status: 502 - code: api_unreachable category: Transport transport: client-only retryable: null message: The Ablo API could not be reached from this machine — the dial failed before any request arrived. Check the network, any proxy, and an ABLO_API_URL override, then retry. doc_url: https://docs.abloatai.com/errors#api_unreachable - code: base_url_missing category: Transport transport: client-only retryable: null message: The client has no base URL configured, so it cannot address the server. Set the base URL when constructing the client. doc_url: https://docs.abloatai.com/errors#base_url_missing - code: cli_database_unreachable category: Transport transport: client-only retryable: null message: The database named by the connection string could not be reached from this machine. The host, port, network, or credential refused the dial before any statement ran. doc_url: https://docs.abloatai.com/errors#cli_database_unreachable - code: commit_failed category: Transport transport: http retryable: true message: The commit reached the server but failed to apply. Retrying may succeed. doc_url: https://docs.abloatai.com/errors#commit_failed http_status: 500 - code: commit_no_result category: Transport transport: http retryable: true message: The commit was sent, but no result frame arrived, so its outcome is unknown. It is safe to retry. doc_url: https://docs.abloatai.com/errors#commit_no_result http_status: 504 - code: commit_offline_grace_expired category: Transport transport: http retryable: false message: The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns. doc_url: https://docs.abloatai.com/errors#commit_offline_grace_expired http_status: 503 - code: data_source_blocked category: Transport transport: http retryable: false message: This branch's database connection is not ready. Check its credentials and configuration; Ablo will not send reads or writes anywhere else. doc_url: https://docs.abloatai.com/errors#data_source_blocked http_status: 503 - code: delivery_partition_mismatch category: Transport transport: http retryable: true message: The connection reached a gateway that does not own its delivery partition. Retry through the cell router. doc_url: https://docs.abloatai.com/errors#delivery_partition_mismatch http_status: 503 - code: exchange_malformed_response category: Transport transport: http retryable: true message: The credential exchange returned a response that could not be parsed. Retrying may succeed. doc_url: https://docs.abloatai.com/errors#exchange_malformed_response http_status: 502 - code: exchange_network_error category: Transport transport: http retryable: true message: A network error interrupted the credential exchange. Check connectivity and retry. doc_url: https://docs.abloatai.com/errors#exchange_network_error http_status: 503 - code: fetch_unavailable category: Transport transport: client-only retryable: null message: This environment provides no `fetch` implementation, so HTTP requests cannot be made. Run on a platform with `fetch` (Node 18+, modern browsers) or supply a polyfill. doc_url: https://docs.abloatai.com/errors#fetch_unavailable - code: flush_timeout category: Transport transport: http retryable: true message: Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes. doc_url: https://docs.abloatai.com/errors#flush_timeout http_status: 504 - code: identity_network_error category: Transport transport: http retryable: true message: A network error occurred while resolving your identity. Check connectivity and retry. doc_url: https://docs.abloatai.com/errors#identity_network_error http_status: 503 - code: instance_at_capacity category: Transport transport: http retryable: true message: The server is at connection capacity. Retry shortly — transient and not specific to your credentials. doc_url: https://docs.abloatai.com/errors#instance_at_capacity http_status: 503 - code: malformed_response category: Transport transport: http retryable: false message: The server sent a message this client could not read, so it was declined whole rather than applied in part. Nothing was changed locally. This normally means the client and the server are running different versions; upgrading the client resolves it. doc_url: https://docs.abloatai.com/errors#malformed_response http_status: 502 - code: protocol_version_unsupported category: Transport transport: http retryable: false message: The client sync-protocol version is outside the range this server supports — upgrade the SDK (or the server was rolled back mid-fleet). doc_url: https://docs.abloatai.com/errors#protocol_version_unsupported http_status: 426 - code: queue_too_deep category: Transport transport: http retryable: true message: The line is already past its depth limit. For a claim, more participants were waiting than your `maxQueueDepth` allows — claim again without the cap to wait anyway, or work elsewhere and retry later. For a write, the transaction queue is draining — retry shortly. doc_url: https://docs.abloatai.com/errors#queue_too_deep http_status: 503 - code: replication_lag_timeout category: Transport transport: http retryable: true message: The data source accepted the write, but its correlated authoritative source delta did not arrive before the confirmation deadline. The write may still materialize; retry with the same idempotency key or wait for source ingestion to recover. doc_url: https://docs.abloatai.com/errors#replication_lag_timeout http_status: 504 - code: response_unrecognized category: Transport transport: client-only retryable: null message: The server answered successfully, but with a body this client does not recognize. The client may be older than the server — update it and retry. doc_url: https://docs.abloatai.com/errors#response_unrecognized - code: source_connector_disconnected category: Transport transport: http retryable: true message: The localhost Data Source connector disconnected with a request in flight. The connector reconnects automatically; retry after it reports ready. doc_url: https://docs.abloatai.com/errors#source_connector_disconnected http_status: 503 - code: source_connector_not_attached category: Transport transport: http retryable: true message: This branch uses localhost connector-only storage, but no connector is attached. Start or restart `ablo dev --local` and keep that process running. doc_url: https://docs.abloatai.com/errors#source_connector_not_attached http_status: 503 - code: source_connector_protocol_error category: Transport transport: http retryable: false message: The CLI and Ablo service disagreed on the Data Source connector frame protocol, or a malformed frame arrived. Upgrade the Ablo CLI and SDK together, then restart `ablo dev --local`. doc_url: https://docs.abloatai.com/errors#source_connector_protocol_error http_status: 400 - code: source_connector_send_failed category: Transport transport: http retryable: true message: The connector socket closed while Ablo was forwarding a signed Data Source request. Keep `ablo dev --local` running; Ablo retries after the connector reconnects. doc_url: https://docs.abloatai.com/errors#source_connector_send_failed http_status: 502 - code: source_connector_shutdown category: Transport transport: http retryable: true message: The Ablo service shut down the connector while a request was in flight. The connector reconnects automatically after the service returns. doc_url: https://docs.abloatai.com/errors#source_connector_shutdown http_status: 503 - code: source_connector_superseded category: Transport transport: http retryable: true message: A newer localhost Data Source connector replaced this one. Stop duplicate `ablo dev --local` processes and use the newest process; in-flight requests are safe to retry. doc_url: https://docs.abloatai.com/errors#source_connector_superseded http_status: 503 - code: source_connector_timeout category: Transport transport: http retryable: true message: The local Data Source handler did not answer before the connector deadline. Check the local Postgres connection and handler logs; the same idempotent request may be retried. doc_url: https://docs.abloatai.com/errors#source_connector_timeout http_status: 504 - code: source_network_error category: Transport transport: http retryable: true message: A network error occurred while talking to the data source. For localhost mode, keep `ablo dev --local` running and check its connector output; for a direct source, check database connectivity and retry. doc_url: https://docs.abloatai.com/errors#source_network_error http_status: 503 - code: source_request_failed category: Transport transport: http retryable: true message: The signed Data Source returned a failure without a more specific code. Inspect the `ablo dev --local` process or deployed endpoint logs, then retry with the same idempotency key. doc_url: https://docs.abloatai.com/errors#source_request_failed http_status: 502 - code: source_unreachable category: Transport transport: http retryable: true message: Ablo could not safely reach the registered direct data source before completing the write. The write remains pinned to direct; retry the same idempotency key after connectivity recovers. doc_url: https://docs.abloatai.com/errors#source_unreachable http_status: 503 - code: sync_not_ready category: Transport transport: client-only retryable: null message: A sync operation ran before the client finished initializing. Wait for the client to be ready before syncing. doc_url: https://docs.abloatai.com/errors#sync_not_ready - code: wait_for_timeout category: Transport transport: http retryable: true message: A wait-for condition timed out before it was satisfied. Retry, or extend the timeout. doc_url: https://docs.abloatai.com/errors#wait_for_timeout http_status: 504 - code: ws_not_ready category: Transport transport: client-only retryable: null message: A frame was sent before the WebSocket connection was established. Wait for the connection to open before sending. doc_url: https://docs.abloatai.com/errors#ws_not_ready - code: connection_limit_exceeded category: Rate limit transport: http retryable: true message: Too many concurrent WebSocket connections for this principal or organization. Close idle connections, or retry once others drain. doc_url: https://docs.abloatai.com/errors#connection_limit_exceeded http_status: 429 - code: quota_exceeded category: Rate limit transport: http retryable: true message: Your organization has used up its configured usage quota. Requests will succeed again once the quota resets or the limit is raised. doc_url: https://docs.abloatai.com/errors#quota_exceeded http_status: 429 - code: rate_limit_exceeded category: Rate limit transport: http retryable: true message: This API key is sending requests faster than its rate limit allows. Slow down and retry after the delay in the `Retry-After` header. doc_url: https://docs.abloatai.com/errors#rate_limit_exceeded http_status: 429 - code: better_auth_upstream_failed category: Server transport: http retryable: true message: The authentication service could not complete the request. Retry the request; if it continues to fail, contact support. doc_url: https://docs.abloatai.com/errors#better_auth_upstream_failed http_status: 500 - code: capability_auth_disabled category: Server transport: http retryable: false message: Capability authentication is disabled on this server. doc_url: https://docs.abloatai.com/errors#capability_auth_disabled http_status: 503 - code: capability_rotation_unavailable category: Server transport: http retryable: false message: This capability could not be rotated, because the environment it belongs to could not be read from it. It is unchanged and still works. Create a replacement capability and retire this one. doc_url: https://docs.abloatai.com/errors#capability_rotation_unavailable http_status: 500 - code: entity_fetch_failed category: Server transport: http retryable: true message: The server failed to fetch the requested entity. It is safe to retry. doc_url: https://docs.abloatai.com/errors#entity_fetch_failed http_status: 500 - code: internal_error category: Server transport: http retryable: true message: Something went wrong on Ablo's side — an unexpected server error. It is safe to retry. doc_url: https://docs.abloatai.com/errors#internal_error http_status: 500 - code: item_id_missing category: Server transport: http retryable: true message: The item-create response arrived without an item id, so the result cannot be used. Retry the request. doc_url: https://docs.abloatai.com/errors#item_id_missing http_status: 502 - code: migration_failed category: Server transport: http retryable: false message: The schema migration failed while applying and did not complete. doc_url: https://docs.abloatai.com/errors#migration_failed http_status: 500 - code: mint_failed category: Server transport: http retryable: true message: Ablo could not mint the requested runtime credential. Retry shortly. doc_url: https://docs.abloatai.com/errors#mint_failed http_status: 502 - code: operational_warning category: Server transport: client-only retryable: null message: Ablo handled an operational degradation that remains searchable for diagnosis. doc_url: https://docs.abloatai.com/errors#operational_warning - code: presigned_url_failed category: Server transport: http retryable: true message: The server could not generate a presigned upload URL. It is safe to retry. doc_url: https://docs.abloatai.com/errors#presigned_url_failed http_status: 500 - code: provisioner_unavailable category: Server transport: http retryable: false message: This deployment has no database provisioner configured, so tables cannot be created here. doc_url: https://docs.abloatai.com/errors#provisioner_unavailable http_status: 503 - code: quota_lookup_failed category: Server transport: http retryable: true message: The server could not load this organization's quota state, so the request was rejected rather than admitted unchecked. Retry shortly. doc_url: https://docs.abloatai.com/errors#quota_lookup_failed http_status: 503 - code: rate_limiter_unavailable category: Server transport: http retryable: true message: The rate-limiter backend is unavailable and this endpoint is configured to fail closed; retry shortly. doc_url: https://docs.abloatai.com/errors#rate_limiter_unavailable http_status: 503 - code: session_check_failed category: Server transport: http retryable: true message: Ablo could not verify the current login session. Retry shortly. doc_url: https://docs.abloatai.com/errors#session_check_failed http_status: 503 - code: source_connector_handler_error category: Server transport: http retryable: true message: The local signed Data Source handler threw while processing a request. Read the `ablo dev --local` error immediately above it, fix the database or adapter failure, and retry. doc_url: https://docs.abloatai.com/errors#source_connector_handler_error http_status: 500 - code: source_connector_internal_error category: Server transport: http retryable: true message: Ablo could not establish the Data Source reverse channel because of an internal service failure. Retry; if it persists, report the request id. doc_url: https://docs.abloatai.com/errors#source_connector_internal_error http_status: 500 - code: tenant_routing_failed category: Server transport: http retryable: true message: The org's registered database could not be resolved or dialed. Ablo never falls back to shared storage for a dedicated tenant — retry, and check the datasource status if it persists. doc_url: https://docs.abloatai.com/errors#tenant_routing_failed http_status: 500 - code: upload_not_configured category: Server transport: http retryable: false message: 'Uploads are not configured on this deployment: the upload storage bucket and CDN domain are unset.' doc_url: https://docs.abloatai.com/errors#upload_not_configured http_status: 503 - code: db_cleanup_failed category: Client (SDK) invariants transport: client-only retryable: null message: Authenticated local data could not be completely removed from this device. doc_url: https://docs.abloatai.com/errors#db_cleanup_failed - code: db_identity_mismatch category: Client (SDK) invariants transport: client-only retryable: null message: The local database is connected to a different organization, project, or branch. doc_url: https://docs.abloatai.com/errors#db_identity_mismatch - code: db_not_opened category: Client (SDK) invariants transport: client-only retryable: null message: The local database was accessed before it was opened. doc_url: https://docs.abloatai.com/errors#db_not_opened - code: db_secure_hash_unavailable category: Client (SDK) invariants transport: client-only retryable: null message: Secure local persistence requires Web Crypto SHA-256 support. doc_url: https://docs.abloatai.com/errors#db_secure_hash_unavailable - code: db_store_not_found category: Client (SDK) invariants transport: client-only retryable: null message: The requested IndexedDB object store does not exist. doc_url: https://docs.abloatai.com/errors#db_store_not_found - code: db_unknown_action_type category: Client (SDK) invariants transport: client-only retryable: null message: An unknown database action type was dispatched. doc_url: https://docs.abloatai.com/errors#db_unknown_action_type - code: idb_unavailable category: Client (SDK) invariants transport: client-only retryable: null message: IndexedDB is unavailable in this environment. doc_url: https://docs.abloatai.com/errors#idb_unavailable - code: invalid_options category: Client (SDK) invariants transport: client-only retryable: null message: The Ablo client was constructed with invalid or incomplete options. doc_url: https://docs.abloatai.com/errors#invalid_options - code: lazy_ref_db_missing category: Client (SDK) invariants transport: client-only retryable: null message: A lazy reference was resolved without a database handle. doc_url: https://docs.abloatai.com/errors#lazy_ref_db_missing - code: lazy_ref_pool_missing category: Client (SDK) invariants transport: client-only retryable: null message: A lazy reference was resolved without a model pool. doc_url: https://docs.abloatai.com/errors#lazy_ref_pool_missing - code: meta_db_not_initialized category: Client (SDK) invariants transport: client-only retryable: null message: The meta database was accessed before initialization. doc_url: https://docs.abloatai.com/errors#meta_db_not_initialized - code: mock_mutation_failed category: Client (SDK) invariants transport: client-only retryable: null message: A mock mutation adapter was configured to fail. doc_url: https://docs.abloatai.com/errors#mock_mutation_failed - code: mock_unsupported_operation category: Client (SDK) invariants transport: client-only retryable: null message: A mock adapter received an unsupported operation. doc_url: https://docs.abloatai.com/errors#mock_unsupported_operation - code: model_class_not_registered category: Client (SDK) invariants transport: client-only retryable: null message: The model class is not registered with the store. doc_url: https://docs.abloatai.com/errors#model_class_not_registered - code: model_disposed category: Client (SDK) invariants transport: client-only retryable: null message: The model instance has been disposed. doc_url: https://docs.abloatai.com/errors#model_disposed - code: model_not_in_schema category: Client (SDK) invariants transport: client-only retryable: null message: A model was accessed on a client whose schema projection leaves it out. doc_url: https://docs.abloatai.com/errors#model_not_in_schema - code: model_not_registered category: Client (SDK) invariants transport: client-only retryable: null message: The model is not registered with the store. doc_url: https://docs.abloatai.com/errors#model_not_registered - code: mutator_registry_duplicate category: Client (SDK) invariants transport: client-only retryable: null message: Two mutator definitions registered under the same name. doc_url: https://docs.abloatai.com/errors#mutator_registry_duplicate - code: mutator_registry_unnamed_def category: Client (SDK) invariants transport: client-only retryable: null message: A mutator definition was registered without a name. doc_url: https://docs.abloatai.com/errors#mutator_registry_unnamed_def - code: mutators_schema_missing category: Client (SDK) invariants transport: client-only retryable: null message: Mutators were registered without a schema. doc_url: https://docs.abloatai.com/errors#mutators_schema_missing - code: no_ablo_provider category: Client (SDK) invariants transport: client-only retryable: null message: An Ablo hook was used outside of an Ablo provider. doc_url: https://docs.abloatai.com/errors#no_ablo_provider - code: no_sync_group_provider category: Client (SDK) invariants transport: client-only retryable: null message: A sync-group hook was used outside of its provider. doc_url: https://docs.abloatai.com/errors#no_sync_group_provider - code: pool_model_class_not_registered category: Client (SDK) invariants transport: client-only retryable: null message: The model class is not registered with the pool. doc_url: https://docs.abloatai.com/errors#pool_model_class_not_registered - code: pool_registry_missing category: Client (SDK) invariants transport: client-only retryable: null message: The model pool registry is not initialized. doc_url: https://docs.abloatai.com/errors#pool_registry_missing - code: pool_subscribe_unregistered category: Client (SDK) invariants transport: client-only retryable: null message: Subscribed to a model that is not registered with the pool. doc_url: https://docs.abloatai.com/errors#pool_subscribe_unregistered - code: query_returns_unknown_model category: Client (SDK) invariants transport: client-only retryable: null message: A query returned a model the registry does not know. doc_url: https://docs.abloatai.com/errors#query_returns_unknown_model - code: registry_invalid_constructor category: Client (SDK) invariants transport: client-only retryable: null message: A model was registered with an invalid constructor. doc_url: https://docs.abloatai.com/errors#registry_invalid_constructor - code: registry_not_initialized category: Client (SDK) invariants transport: client-only retryable: null message: The registry was used before initialization. doc_url: https://docs.abloatai.com/errors#registry_not_initialized - code: registry_property_conflict category: Client (SDK) invariants transport: client-only retryable: null message: Two registered models declared a conflicting property. doc_url: https://docs.abloatai.com/errors#registry_property_conflict - code: registry_reference_unknown_target category: Client (SDK) invariants transport: client-only retryable: null message: A relation referenced an unknown target model. doc_url: https://docs.abloatai.com/errors#registry_reference_unknown_target - code: registry_reference_unresolved category: Client (SDK) invariants transport: client-only retryable: null message: A relation reference could not be resolved. doc_url: https://docs.abloatai.com/errors#registry_reference_unresolved - code: registry_unknown_model category: Client (SDK) invariants transport: client-only retryable: null message: The registry has no entry for the requested model. doc_url: https://docs.abloatai.com/errors#registry_unknown_model - code: store_create_schema_missing category: Client (SDK) invariants transport: client-only retryable: null message: Store.create was called without a schema. doc_url: https://docs.abloatai.com/errors#store_create_schema_missing - code: store_manager_unknown_model category: Client (SDK) invariants transport: client-only retryable: null message: The store manager has no entry for the requested model. doc_url: https://docs.abloatai.com/errors#store_manager_unknown_model - code: store_query_schema_missing category: Client (SDK) invariants transport: client-only retryable: null message: Store.query was called without a schema. doc_url: https://docs.abloatai.com/errors#store_query_schema_missing - code: store_query_unknown_model category: Client (SDK) invariants transport: client-only retryable: null message: Store.query named a model the store does not know. doc_url: https://docs.abloatai.com/errors#store_query_unknown_model - code: sync_client_db_missing category: Client (SDK) invariants transport: client-only retryable: null message: The sync client has no database handle. doc_url: https://docs.abloatai.com/errors#sync_client_db_missing - code: sync_context_missing_provider category: Client (SDK) invariants transport: client-only retryable: null message: Sync context was read outside of its provider. doc_url: https://docs.abloatai.com/errors#sync_context_missing_provider - code: transaction_mutate_unknown_model category: Client (SDK) invariants transport: client-only retryable: null message: A transaction mutated a model the registry does not know. doc_url: https://docs.abloatai.com/errors#transaction_mutate_unknown_model - code: transaction_read_unknown_model category: Client (SDK) invariants transport: client-only retryable: null message: A transaction read a model the registry does not know. doc_url: https://docs.abloatai.com/errors#transaction_read_unknown_model - code: undo_entry_invalid category: Client (SDK) invariants transport: client-only retryable: null message: An undo entry failed inverse-op schema validation. doc_url: https://docs.abloatai.com/errors#undo_entry_invalid - code: undo_scope_schema_missing category: Client (SDK) invariants transport: client-only retryable: null message: An undo scope was opened without a schema. doc_url: https://docs.abloatai.com/errors#undo_scope_schema_missing