Error codes

Every error Ablo returns, by category. This page is generated from the canonical registry — its anchors are the target of each error's doc_url.

Error contract version: 2026-09-20 (also sent on the Ablo-Version response header).

Every error — over HTTP or WebSocket — carries the same envelope:

{
  "type": "AbloValidationError",
  "code": "invalid_body",
  "message": "The request body was missing, unparseable, or the wrong shape.",
  "doc_url": "https://docs.abloatai.com/errors#invalid_body",
  "request_id": "req_8f3a…"
}

type is the coarse class (catch with instanceof, or switch on it); code is the stable machine identifier documented below; request_id correlates to your server logs. Some errors carry extra structured fields (e.g. a schema push adds warnings).

Authentication

Missing, invalid, revoked, or expired credentials. Re-authenticate.

api_key_required

HTTP 401 · not retryable

This operation requires an API key, and none was presented. Send one as Authorization: Bearer <key>.

apikey_expired

HTTP 401 · not retryable

This ephemeral API key has expired. Mint a fresh key from your still-valid session and retry the request.

apikey_invalid

HTTP 401 · not retryable

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.

apikey_missing

HTTP 401 · not retryable

The request arrived without an API key. Send one as Authorization: Bearer <key>.

apikey_revoked

HTTP 401 · not retryable

This API key has been revoked and can no longer be used. Mint a new key from the dashboard.

apikey_rotation_expired

HTTP 401 · not retryable

This API key’s rotation grace period has ended. Deploy its replacement key, then restart any runtime that reads the key from its environment.

auth_no_credentials

HTTP 401 · not retryable

No recognized authentication credential was presented — no API key and no bearer JWT. Send Authorization: Bearer <token>.

better_auth_request_failed

HTTP 400 · not retryable

The authentication request was rejected. Check the submitted credentials or request and try again.

browser_apikey_blocked

client-only · not sent over the network

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.

capability_id_missing

HTTP 401 · not retryable

This request must name a capability id, but none was provided.

capability_required

HTTP 401 · not retryable

This operation requires a capability, and none was presented.

cli_api_key_missing

client-only · not sent over the network

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.

exchange_failed

HTTP 401 · not retryable

The API key could not be exchanged for a working credential — the exchange was rejected. Check that the key is still valid.

file_upload_auth_required

HTTP 401 · not retryable

File uploads require an authenticated session. Sign in and retry.

identity_missing_organization

HTTP 401 · not retryable

Authentication succeeded, but the credential resolves to no organization, so requests cannot be scoped. Check that the key or token carries an organization.

identity_resolve_failed

HTTP 401 · not retryable

The server could not resolve an identity for this credential — the identity lookup was rejected. Check that the credential is still valid.

jwt_audience_mismatch

HTTP 401 · not retryable

The bearer JWT’s aud (audience) claim does not match the audience this issuer is registered with.

jwt_expired

HTTP 401 · not retryable

The bearer JWT has expired. Obtain a fresh token from your identity provider and retry.

jwt_invalid

HTTP 401 · not retryable

The bearer JWT failed validation for a reason the server could not classify further. Check the token’s issuer, signature, audience, and expiry.

jwt_issuer_untrusted

HTTP 401 · not retryable

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.

jwt_malformed

HTTP 401 · not retryable

The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent.

jwt_missing_issuer

HTTP 401 · not retryable

The bearer JWT has no iss (issuer) claim, so it cannot be routed to a trusted issuer.

jwt_missing_organization

HTTP 401 · not retryable

The bearer JWT carries no organization context — neither a fixed org for the issuer nor the configured organization claim.

jwt_missing_subject

HTTP 401 · not retryable

The bearer JWT has no sub (subject) claim to identify the user.

jwt_org_membership_denied

HTTP 403 · not retryable

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).

jwt_signature_invalid

HTTP 401 · not retryable

The bearer JWT’s signature could not be verified against the issuer’s JWKS (wrong key, rotated key, or forged token).

session_expired

HTTP 401 · not retryable

Your session has expired or is no longer valid. Sign in again to continue.

source_api_key_missing

HTTP 401 · not retryable

The Data Source handler has no signing key configured. Configure it with the signing key from the current Data Source registration.

source_api_key_unresolved

HTTP 401 · not retryable

The API key presented for this data source could not be resolved to a known key. Check the key and its environment.

source_connector_unauthenticated

HTTP 401 · not retryable

The localhost Data Source connector could not authenticate. Rerun ablo dev --local so it mints and uses a fresh branch-bound secret key.

source_id_missing

HTTP 401 · not retryable

The signed Data Source request did not include its webhook id. Check that the request reaches the handler without an intermediary removing Standard Webhooks headers.

source_signature_invalid

HTTP 401 · not retryable

The Data Source rejected Ablo’s signature. Configure the endpoint or localhost connector with the signing key from the current Data Source registration.

source_signature_missing

HTTP 401 · not retryable

The signed Data Source request did not include its webhook signature. Check that the request reaches the handler without an intermediary removing Standard Webhooks headers.

source_timestamp_expired

HTTP 401 · not retryable

The signed Data Source request fell outside the allowed clock-skew window. Synchronize the endpoint host clock, then retry.

source_timestamp_invalid

HTTP 401 · not retryable

The signed Data Source request carried an invalid webhook timestamp.

source_timestamp_missing

HTTP 401 · not retryable

The signed Data Source request did not include its webhook timestamp. Check that the request reaches the handler without an intermediary removing Standard Webhooks headers.

unknown_auth_host

HTTP 400 · not retryable

The authentication host is not recognized.

Permission

Credentials were valid but the action is forbidden for this caller.

branch_scope_denied

HTTP 403 · not retryable

The request targeted a branch the caller’s key is not scoped to.

byo_host_not_allowed

HTTP 403 · not retryable

The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used.

byo_role_cannot_enforce_rls

HTTP 403 · not retryable

The direct Postgres connector role cannot enforce row-level security.

byo_role_unreadable

HTTP 403 · not retryable

The direct Postgres connector role could not be introspected.

byo_tenant_tables_unforced_rls

HTTP 403 · not retryable

Tenant tables do not have RLS forced under the direct Postgres connector role.

database_host_not_allowed

HTTP 403 · not retryable

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.

database_role_cannot_enforce_rls

HTTP 403 · not retryable

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.

database_role_unreadable

HTTP 403 · not retryable

Ablo could not introspect the database role it connects with, so it cannot verify that row-level security is enforced.

database_tables_unforced_rls

HTTP 403 · not retryable

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.

forbidden

HTTP 403 · not retryable

The caller lacks permission for this operation.

issuer_register_forbidden

HTTP 403 · not retryable

Registering a trusted issuer requires a secret (sk_) API key. The key presented is not a secret key.

organization_disabled

HTTP 403 · not retryable

This organization has been disabled by an operator. Contact support before retrying.

organization_mismatch

HTTP 403 · not retryable

The request targeted an organization the caller is not scoped to.

permission_denied

HTTP 403 · not retryable

The participant is not allowed to execute this mutator.

project_scope_denied

HTTP 403 · not retryable

The request targeted a project the caller’s key is not scoped to.

schema_provisioning_forbidden

HTTP 403 · not retryable

Schema registration could not create tables in the target database: the engine is not permitted to run DDL there.

server_side_only

HTTP 403 · not retryable

This endpoint is available only to trusted server-side callers.

source_connector_production_not_enabled

HTTP 403 · not retryable

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.

source_connector_requires_secret_key

HTTP 403 · not retryable

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.

source_forbidden

HTTP 403 · not retryable

The Data Source key is not allowed to perform this operation.

wide_scope_forbidden

HTTP 403 · not retryable

This caller may not use a wide scope. Request a scope narrowed to the resources you need.

Capability

The connection’s resolved scope does not cover the attempted action.

capability_invalid

HTTP 403 · not retryable

This capability cannot be used — it is unknown, revoked, or expired. Request a fresh grant.

capability_scope_denied

HTTP 403 · not retryable

This action falls outside the scope granted to the connection, so it was denied.

Claim contention

The target is held by another participant, or a claim lease could not be acquired. Usually retryable once the holder releases.

claim_conflict

HTTP 409 · not retryable

Another participant holds a claim on this row, so the write was rejected. Take a claim with ablo.<model>.claim to queue fairly behind the holder, or re-read and rebase.

claim_lease_unavailable

HTTP 503 · retryable

The claim-lease coordination subsystem is temporarily unavailable, so the claim could not be processed. Retry shortly.

claim_lost

HTTP 409 · not retryable

The claim held on this row was lost before the write could apply. Re-acquire with ablo.<model>.claim and retry from its fresh snapshot.

claim_not_wired

client-only · not sent over the network

Claims were used, but this runtime has no claim support wired in. The standard Ablo({ schema, apiKey }) client wires it up automatically.

claim_queued

HTTP 409 · retryable

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.

claim_wait_aborted

HTTP 409 · retryable

The wait for this claim lease was aborted before the lease was granted.

entity_claimed

HTTP 409 · not retryable

This row is currently claimed by another participant, so the write was blocked. Queue behind the holder with ablo.<model>.claim, or wait for the claim to clear.

fence_token_stale

HTTP 409 · not retryable

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.

grant_timeout

HTTP 504 · retryable

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.

model_claim_not_configured

client-only · not sent over the network

Claiming is unavailable on this model client. Construct it through the standard Ablo({ schema, apiKey }) client and retry.

model_claimed

HTTP 409 · not retryable

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.

model_claimed_timeout

HTTP 409 · not retryable

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.

Conflict

The write collided with concurrent state (stale read, idempotency mismatch, incompatible change).

contention_exhausted

client-only · not sent over the network

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.

database_already_connected

HTTP 409 · not retryable

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.

decision_contended

HTTP 409 · retryable

Another transaction is evaluating the same decision rows. Retry the unchanged request shortly.

entity_already_exists

HTTP 409 · not retryable

A row already exists with this id. CREATE is strict; use UPDATE for an existing row.

foreign_key_violation

HTTP 409 · not retryable

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.

idempotency_conflict

HTTP 409 · not retryable

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.

idempotency_key_expired

HTTP 409 · not retryable

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.

incompatible_change

HTTP 409 · not retryable

The schema change is incompatible with the schema currently deployed and cannot be applied as-is.

precondition_failed

HTTP 409 · not retryable

A conditional operation did not match the current database row. The complete atomic commit was rejected and no operation in the batch was applied.

replication_reset_required

HTTP 409 · not retryable

This branch has live replicated rows for a mapped model that disappeared. Declare a rename or an explicit drop/reset before advancing the schema.

source_transport_pinned

HTTP 409 · not retryable

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.

stale_context

HTTP 409 · not retryable

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.

unique_violation

HTTP 409 · not retryable

The write duplicates a value that must be unique — another row already holds it. Choose a different value, or update the existing row.

update_aborted

client-only · not sent over the network

The functional update was aborted via its AbortSignal before the write landed; nothing was written.

Validation

The request payload or parameters were invalid. Fix the input and retry.

agent_perception_missing_context

HTTP 422 · not retryable

The agent perception request is missing context it needs to run. Include the required context fields and retry.

capability_id_required

HTTP 400 · not retryable

A capability id is required for this request.

check_violation

HTTP 400 · not retryable

The database rejected a value that fails one of its check constraints. The error details name the constraint; adjust the value and retry.

claim_id_required

HTTP 400 · not retryable

A claim id is required for this request.

cli_database_url_missing

client-only · not sent over the network

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.

cli_invalid_arguments

client-only · not sent over the network

The CLI was invoked with an unknown flag or a malformed flag value.

column_type_mismatch

HTTP 400 · not retryable

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.

column_value_out_of_range

HTTP 400 · not retryable

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.

commit_operation_action_required

HTTP 400 · not retryable

A commit operation is missing its action.

commit_operation_invalid

HTTP 400 · not retryable

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.

commit_operation_model_required

HTTP 400 · not retryable

A commit operation is missing its model.

commit_operation_required

HTTP 400 · not retryable

A commit must carry operation or operations.

commit_operation_unsupported

HTTP 400 · not retryable

A commit operation used an unsupported action.

commit_operations_ambiguous

HTTP 400 · not retryable

A commit supplied both operation and operations. Send one or the other, not both.

commit_too_many_operations

HTTP 400 · not retryable

A commit exceeded the per-commit operation limit; split it into smaller batches.

constraint_violation

HTTP 400 · not retryable

The database rejected the write on an integrity constraint. The error details identify the specific constraint.

data_session_unsupported

HTTP 400 · not retryable

This sign-in host cannot create the requested data session.

database_loopback_requires_connector

HTTP 400 · not retryable

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.

database_not_replication_ready

HTTP 400 · not retryable

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.

database_unreachable

HTTP 400 · not retryable

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.

datasource_connection_unsupported

HTTP 400 · not retryable

This deployment does not accept direct connection-string data sources. Register a signed Data Source endpoint instead.

duration_invalid

client-only · not sent over the network

A duration value was not a number of seconds or a “500ms” | “30s” | “3m” | “24h” string.

events_required

HTTP 400 · not retryable

The request must include a non-empty events array.

idempotency_key_too_long

HTTP 400 · not retryable

The supplied Idempotency-Key exceeds the maximum length. Use a shorter key — a UUID works well.

ingest_failed

HTTP 400 · not retryable

The source-event batch was rejected during ingest and nothing was appended. Check the events against the expected shape and re-send.

invalid_body

HTTP 400 · not retryable

The request body was missing, unparseable, or the wrong shape.

invalid_id

HTTP 400 · not retryable

The id in the request is not a valid identifier.

invalid_input

HTTP 400 · not retryable

The mutator input could not be parsed or failed input validation.

invalid_json

HTTP 400 · not retryable

The request body was not valid JSON.

invalid_model

HTTP 400 · not retryable

The model name in the request is not a valid model identifier.

invalid_participant_kind

HTTP 400 · not retryable

The participant kind is not one the server recognizes.

invalid_request

HTTP 400 · not retryable

The request parameters were invalid.

invalid_schema

HTTP 400 · not retryable

The submitted schema could not be parsed.

invalid_sync_group

HTTP 400 · not retryable

Sync groups must be default or <namespace>:<id>.

item_id_required

HTTP 400 · not retryable

An item id is required for this request.

malformed_claim

HTTP 400 · not retryable

The claim payload could not be parsed. A row claim must name the model and entity it targets. Check the payload shape and resend.

malformed_subscription

HTTP 400 · not retryable

The update_subscription payload was malformed; expected { syncGroups: string[] }.

mesh_message_from_id_spoof

HTTP 403 · not retryable

The mesh message’s from id does not match the authenticated sender, so it was rejected — participants may only send as themselves.

mesh_message_from_kind_mismatch

HTTP 403 · not retryable

The mesh message’s from kind does not match the kind of the authenticated sender, so it was rejected.

mesh_message_invalid_input

HTTP 400 · not retryable

The mesh message payload failed input validation and was not delivered.

model_identifier_missing

HTTP 400 · not retryable

The payload is missing the model’s identifier, so the target row cannot be determined. Include the id field.

model_query_failed

HTTP 400 · not retryable

The model query failed to execute. Check the query filters and operators.

model_required_field_missing

HTTP 400 · not retryable

The write is missing a field the model marks as required. Include the field and retry.

narrow_scope_required

HTTP 400 · not retryable

This request requires a scope narrowed to specific resources; the presented scope is too broad.

not_null_violation

HTTP 400 · not retryable

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.

org_id_required

HTTP 400 · not retryable

An organization id is required for this request.

position_missing_parent

HTTP 400 · not retryable

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.

position_unknown_sibling

HTTP 400 · not retryable

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.

presence_identity_required

HTTP 400 · not retryable

Presence requests must carry both userId and organizationId.

project_slug_taken

HTTP 409 · not retryable

A project with this slug already exists in the organization. Choose a different slug.

queries_required

HTTP 400 · not retryable

The request must include a non-empty queries array.

query_invalid_boolean

HTTP 400 · not retryable

The query compared a boolean column against an invalid boolean literal.

query_invalid_identifier

HTTP 400 · not retryable

The query contained an invalid identifier.

query_invalid_like_pattern

HTTP 400 · not retryable

The LIKE pattern must not end with an escape character.

query_relation_expansion_too_large

HTTP 400 · not retryable

A requested relation expansion exceeds the bounded nested-row budget. Query the related model as its own paginated collection instead.

query_unknown_relation

HTTP 400 · not retryable

The query references a relation the model does not define. Check the relation name against the schema.

query_unsupported_operator

HTTP 400 · not retryable

The query used an unsupported operator.

replication_publication_drift

HTTP 400 · not retryable

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.

request_too_large

HTTP 413 · not retryable

The request body exceeds the maximum size.

schema_definition_invalid

client-only · not sent over the network

A schema definition value was invalid (bad column identifier, non-finite backfill, or unsupported schema-JSON version).

schema_too_large

HTTP 413 · not retryable

The submitted schema exceeds the maximum size.

snapshot_reserved_key

HTTP 400 · not retryable

The snapshot uses a key name that is reserved by the runtime. Rename the key and retry.

source_adapter_misconfigured

client-only · not sent over the network

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.

source_connector_localhost_required

HTTP 400 · not retryable

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.

source_event_invalid

HTTP 400 · not retryable

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.

source_operation_id_required

client-only · not sent over the network

A data-source operation arrived without the entity id it targets.

upload_fields_required

HTTP 400 · not retryable

The upload request is missing a required field.

upload_items_required

HTTP 400 · not retryable

The request must include a non-empty items array.

usage_invalid

HTTP 400 · not retryable

The usage request was invalid.

validation_failed

HTTP 400 · not retryable

The mutator rejected the input because it violates a business rule.

write_options_invalid

client-only · not sent over the network

The write options (idempotencyKey / label / wait / readAt / claim) failed validation against the write-options schema.

write_payload_invalid

client-only · not sent over the network

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.

Not found

The referenced resource does not exist (or is hidden by scope).

capability_not_found

HTTP 404 · not retryable

No capability exists with the given id.

claim_not_found

HTTP 404 · not retryable

No claim of yours exists with the given id. It was released, expired, or belongs to a different branch.

entity_not_found

HTTP 404 · not retryable

No row exists with the requested id. It may have been deleted, or the id may belong to a different environment.

invalid_mutator

HTTP 404 · not retryable

The requested mutator is not registered on this server.

model_not_found

HTTP 404 · not retryable

No row of this model exists with the requested id. It may have been deleted, or the id may belong to a different environment.

mutate_update_entity_not_found

HTTP 404 · not retryable

The row targeted by this update does not exist — it may have been deleted since you read it. Re-read before retrying.

no_data_source_registered

HTTP 404 · not retryable

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.

source_connector_no_source_registered

HTTP 404 · not retryable

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.

Tenant / schema resolution

The named model could not be resolved in the tenant schema.

connected_database_unreachable

HTTP 503 · not retryable

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.

model_not_provisioned

HTTP 409 · not retryable

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.

model_not_tenant_scoped

HTTP 400 · not retryable

This model is not tenant-scoped, so it cannot be queried through the tenant-scoped read path.

mutate_create_unknown_model

HTTP 400 · not retryable

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.

no_active_organization

HTTP 400 · not retryable

Select an active organization before continuing.

server_execute_unknown_model

HTTP 400 · not retryable

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.

source_tenancy_not_enforced

HTTP 400 · not retryable

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'.

tenant_model_columns_unknown

HTTP 400 · not retryable

The columns for this model could not be resolved in the tenant database, so the operation cannot be mapped onto its table.

tenant_model_missing_organization_id

HTTP 400 · not retryable

This model’s table has no organization_id column, which Ablo requires to isolate rows by organization. Add the column before syncing this model.

unknown_model

HTTP 400 · not retryable

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.

user_scope_not_enforced

HTTP 400 · not retryable

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.

Schema

Schema declaration or migration problems.

drop_field

client-only · not sent over the network

This migration would drop an existing field, destroying the data stored in it.

drop_model

client-only · not sent over the network

This migration would drop an entire model and its table, destroying the rows stored in it.

enum_value_removed

client-only · not sent over the network

This migration removes an enum value that existing rows may still hold.

lossy_recreate

client-only · not sent over the network

This migration can only apply by recreating the table, which would not preserve its existing rows.

made_required

client-only · not sent over the network

This migration makes an existing optional field required, which rows without a value for it would violate.

query_relation_target_unknown

HTTP 500 · not retryable

A relation in the query targets a model the schema does not define.

required_field_added

client-only · not sent over the network

This migration adds a new required field that existing rows have no value for.

risky_cast

client-only · not sent over the network

This migration changes a column to a type its current values may not convert to cleanly.

schema_field_consecutive_caps

HTTP 400 · not retryable

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).

schema_field_not_camelcase

HTTP 400 · not retryable

A schema field name is not camelCase. Rename the field (for example dueDate) — Ablo derives column names from camelCase field names.

schema_grants_identifier_unsafe

HTTP 400 · not retryable

A grants declaration references an identifier that is not safe to use in SQL. Use plain column and relation names.

schema_grants_relation_kind

HTTP 400 · not retryable

A grants declaration references a relation of a kind it cannot traverse.

schema_grants_relation_missing

HTTP 400 · not retryable

A grants declaration references a relation the model does not define. Check the relation name against the model.

schema_grants_shape_invalid

HTTP 400 · not retryable

A grants declaration in the schema has an invalid shape and could not be parsed.

schema_grants_target_not_scope_root

HTTP 400 · not retryable

A grants declaration targets a model that is not a scope root, so access cannot be derived from it.

schema_mutable_missing_meta

HTTP 400 · not retryable

The schema is declared mutable but is missing its required meta block.

schema_reserved_field

client-only · not sent over the network

A model declared id, the one universal field Ablo supplies. Remove it from the declared application fields.

schema_scope_invalid

HTTP 500 · not retryable

The model’s scope predicate could not be built.

schema_scope_kind_invalid

HTTP 400 · not retryable

A scope declaration in the schema uses a kind the engine does not recognize.

schema_table_invalid

HTTP 500 · not retryable

The model’s table identifier is invalid.

Bootstrap

Initial snapshot fetch problems.

bootstrap_cancelled

client-only · not sent over the network

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.

bootstrap_fetch_timeout

HTTP 504 · retryable

The initial bootstrap fetch timed out before the server responded. Retry shortly.

bootstrap_offline

HTTP 503 · retryable

Bootstrap could not run because the client is offline. It can proceed once the network returns.

bootstrap_offline_no_cache

HTTP 503 · not retryable

The client is offline and no cached snapshot is available to start from, so there is no data to load until the network returns.

bootstrap_response_invalid

HTTP 502 · retryable

The bootstrap response could not be parsed. Retrying may succeed.

bootstrap_response_schema_invalid

HTTP 502 · retryable

The bootstrap response parsed but failed schema validation, so it was not applied. Retrying may succeed.

Transport

Network, connection, queue, and timeout failures. Generally retryable.

api_unreachable

client-only · not sent over the network

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.

base_url_missing

client-only · not sent over the network

The client has no base URL configured, so it cannot address the server. Set the base URL when constructing the client.

cli_database_unreachable

client-only · not sent over the network

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.

commit_failed

HTTP 500 · retryable

The commit reached the server but failed to apply. Retrying may succeed.

commit_no_result

HTTP 504 · retryable

The commit was sent, but no result frame arrived, so its outcome is unknown. It is safe to retry.

commit_offline_grace_expired

HTTP 503 · not retryable

The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns.

data_source_blocked

HTTP 503 · not retryable

This branch’s database connection is not ready. Check its credentials and configuration; Ablo will not send reads or writes anywhere else.

delivery_partition_mismatch

HTTP 503 · retryable

The connection reached a gateway that does not own its delivery partition. Retry through the cell router.

exchange_malformed_response

HTTP 502 · retryable

The credential exchange returned a response that could not be parsed. Retrying may succeed.

exchange_network_error

HTTP 503 · retryable

A network error interrupted the credential exchange. Check connectivity and retry.

fetch_unavailable

client-only · not sent over the network

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.

flush_timeout

HTTP 504 · retryable

Flushing the transaction queue timed out before every pending write was sent. Retry once connectivity stabilizes.

identity_network_error

HTTP 503 · retryable

A network error occurred while resolving your identity. Check connectivity and retry.

instance_at_capacity

HTTP 503 · retryable

The server is at connection capacity. Retry shortly — transient and not specific to your credentials.

malformed_response

HTTP 502 · not retryable

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.

observation_buffer_overflow

client-only · not sent over the network

A WebSocket observer fell behind its bounded in-memory backlog. Restart observation to replay from the last durable checkpoint.

protocol_version_unsupported

HTTP 426 · not retryable

The client sync-protocol version is outside the range this server supports — upgrade the SDK (or the server was rolled back mid-fleet).

queue_too_deep

HTTP 503 · retryable

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.