Errors

Error codes and what they mean.

This page documents known errors that may be encountered when using Resonate and how to troubleshoot them.

If you believe your issue is not covered here, reach out in Discord to discuss.

Known errors will likely have an error code associated with them and a short error message.

Troubleshooting steps are categorized by error code ranges:

Server request errors#

These are the errors you may encounter when making requests to Resonate Server v0.9.5. Request errors signify problems with the request itself — retrying the same request will not resolve the issue.

Range: HTTP 4XX

Error response shape

Every response from the server (success or error) carries this envelope. On error, head.status is the HTTP status code and data is the human-readable message.

code
{
  "kind": "promises.get",
  "head": {
    "corrId": "<correlation id from the request>",
    "status": 404,
    "version": "2026-04-01"
  },
  "data": "Promise not found"
}

If the problem persists, open a GitHub issue with details, including the response envelope and steps to reproduce. Or reach out via Discord for support.

400 — Bad Request#

The request is malformed. Common causes:

  • Invalid JSON body or missing required fields
  • Validation failure (data carries the failed field and reason)
  • Unrecognized operation kind
  • Invalid resonate:target address
  • Invalid listener address
  • limit outside the allowed range (1–1000)

401 — Unauthorized#

The request did not carry a valid bearer token, or the token failed JWT verification.

403 — Forbidden#

The request carried a valid token, but the principal is not permitted to perform the requested action.

404 — Not Found#

The requested resource does not exist. Common cases: promise not found, schedule not found, task not found, awaited promise not found.

409 — Conflict#

The request would violate an existing resource's lifecycle invariants. Common cases:

  • Promise already resolved, rejected, canceled, or timed out (cannot be modified again)
  • Schedule with the requested id already exists
  • Promise with the requested id already exists
  • Lock already acquired
  • Task already claimed or completed
  • Task claimed with the wrong counter

422 — Unprocessable Entity#

The request was syntactically valid but semantically unprocessable. Common cases:

  • Awaiter promise not found or has no resonate:target tag
  • Task in invalid state for the requested transition

Server errors#

Range: HTTP 5XX

Server errors represent transient or systemic problems that prevent the request from being processed. Retrying the request may resolve the issue.

If the problem persists, open a GitHub issue with details, including the response envelope and steps to reproduce. Or reach out via Discord for support.

500 — Internal Server Error#

An unexpected server-side failure. Includes failures in the persistence layer (e.g. unrecoverable database lock contention), the scheduler, or any unhandled internal error path. The data field carries the failure description; the server logs carry the underlying cause.

Python SDK errors#

These are the exception classes raised by the Python SDK (resonate-sdk v0.6.7). Each exception has a numeric code attribute. Codes are not contiguous integers — they fall into a few ranges keyed off the underlying failure domain.

If the problem persists, open a GitHub issue with details, including the error code and steps to reproduce. Or reach out via Discord for support.

ResonateStoreError (codes 100.x)#

Raised when a store operation against the Resonate Server (or the in-process local store) fails. The fractional part embeds a structured sub-code from the legacy Resonate Server (which Python SDK v0.6.7 targets — see the legacy-server callout on the Python SDK guide). Common sub-codes:

  • 100.40400 — promise/schedule not found
  • 100.40303 — promise already timed out
  • 100.40305 — task already claimed
  • 100.40403 — task not found
  • 100.40399 — state-machine transition error
  • 100.0 — transport-level failure (request timed out, failed to connect, unknown exception)

The current Rust server (v0.9.5) does not emit these structured sub-codes — it returns standard HTTP status codes (see Server request errors above). When the Python SDK adds Rust-server compatibility, this section will be updated.

ResonateCanceledError (code 200)#

Raised when a promise is canceled. The promise_id attribute identifies the canceled promise.

ResonateTimedoutError (code 201)#

Raised when a promise times out before it is resolved or rejected. Carries promise_id and timeout attributes.

ResonateShutdownError (code 300)#

Raised when the Resonate client is shutting down and an in-flight operation cannot proceed.

TypeScript SDK errors#

Range: 1100 - 1199

These are known errors you may encounter when using the TypeScript SDK.

If the problem persists, open a GitHub issue with details, including the error code and steps to reproduce. Or reach out via Discord for support.

1100#

REGISTRY_VERSION_INVALID

Function version must be greater than zero (x provided)

1101#

REGISTRY_NAME_REQUIRED

Function name is required

1102#

REGISTRY_FUNCTION_ALREADY_REGISTERED

Function 'x' (version y) is already registered [under 'u']

1103#

REGISTRY_FUNCTION_NOT_REGISTERED

Function 'x' (version y) is not registered. Will drop.

1104#

DEPENDENCY_ALREADY_REGISTERED

Dependency 'x' is already registered

1105#

DEPENDENCY_NOT_REGISTERED

Dependency 'x' is not registered. Will drop.

1106#

ENCODING_ARGS_UNENCODEABLE

Function arguments cannot be encoded.

1107#

ENCODING_ARGS_UNDECODEABLE

Function arguments cannot be decoded.

1108#

ENCODING_RETV_UNENCODEABLE

The return value from a function cannot be encoded.

1109#

ENCODING_RETV_UNDECODEABLE

The return value from a function cannot be decoded.

1198#

PANIC

An unrecoverable internal error occurred in the SDK.

1199#

SERVER_ERROR

An error occurred on the server. Please check for additional error codes for more details.

Edit this page on GitHub
Debug a Resonate applicationTroubleshooting