General

Error Codes

Every error group and code the Rivet HTTP API and connection protocol can return.

Errors are identified by group and code. See Errors for the response format and Connect for how they arrive over a WebSocket connection.

The Status column shows the HTTP status the error is returned with. When the gateway and the control plane disagree, both are listed. Codes without a status use the default for where they were raised: 400 from the control plane and gateway, and 500 from inside the actor runtime, where the message is also replaced with a generic internal error unless the code is listed here with a status. Errors thrown by your own actor code with UserError use the user group with whatever code you supply, and always return 400.

Messages may contain placeholders in braces that are filled in at runtime. Match on group and code, not on message.

actor api auth compute_gateway config connection datacenter depot engine guard inspector kv message namespace napi pegboard protocol queue registry request runner runner_config serverless_runner_pool sqlite ups user validation wasm ws

actor

Actor lifecycle, addressing, and actions.

Code	Status	Message
`actor.aborted`	`400`	Actor aborted
`actor.action_timed_out`	`408`	Action timed out
`actor.creation_rate_limit`	`429`	Too many actors created at once. Try again later.
`actor.destroyed_during_creation`		Actor was destroyed during creation.
`actor.destroyed_while_waiting_for_ready`		Actor was destroyed while waiting for ready state.
`actor.destroying`		Actor is destroying.
`actor.dropped_reply`		Actor reply channel was dropped without a response.
`actor.duplicate_key`		Actor key already in use.
`actor.empty_key`		Key label cannot be empty.
`actor.input_too_large`		Actor input too large.
`actor.invalid_operation`		Actor operation is invalid.
`actor.invalid_request`	`400`	Invalid hibernatable websocket connection ID
`actor.js_callback_failed`		JavaScript callback failed
`actor.js_callback_unavailable`		JavaScript callback unavailable
`actor.key_index_scan_limit_exceeded`		Too many index entries for this actor key to resolve it.
`actor.key_reserved_in_different_datacenter`		Actor key is already reserved in a different datacenter. Either remove the datacenter constraint to automatically create this actor in the correct datacenter or provide the datacenter that matches.
`actor.key_too_large`		Key label too large.
`actor.kv_key_not_found`		The KV key does not exist for this actor.
`actor.kv_storage_quota_exceeded`		Not enough space left in storage.
`actor.method_not_allowed`	`405`	Method not allowed
`actor.missing_input`		Actor input is missing.
`actor.namespace_not_found`		The namespace does not exist.
`actor.no_runner_config_configured`		No runner config configured in any datacenter. Validate a provider is listed that matches requested pool name.
`actor.not_configured`		Actor capability is not configured.
`actor.not_found`	`404`	The actor does not exist or was destroyed.
`actor.not_ready`		Actor is not ready.
`actor.not_registered`		Actor factory is not registered.
`actor.overloaded`		Actor is overloaded.
`actor.panicked`		Actor task panicked.
`actor.shutdown_timeout`		Actor shutdown timed out.
`actor.starting`		Actor is starting.
`actor.state_mutation_reentrant`		Actor state mutation is re-entrant.
`actor.stopping`		Actor is stopping.
`actor.workflow_in_flight`		Workflow replay is unavailable while the workflow is currently in flight.

api

Malformed requests to the control plane.

Code	Status	Message
`api.bad_request`		Request is invalid
`api.bad_token`		Invalid token provided
`api.forbidden`	`403`	Access denied
`api.internal_error`		An internal server error occurred
`api.not_found`	`404`	The requested resource was not found
`api.unauthorized`	`401`	Authentication required

auth

Token validation and permissions.

Code	Status	Message
`auth.insufficient_permissions`	`403`	Insufficient permissions to access this resource.
`auth.invalid_token`	`401`	Authentication token is invalid.
`auth.issuance_disabled`	`503`	JWT issuance is not enabled for this deployment.
`auth.issuance_unavailable`	`503`	The server could not issue an authentication token because the signing service is temporarily unavailable. Retry the request.
`auth.token_expired`	`401`	Authentication token has expired.
`auth.verification_unavailable`	`503`	The server could not verify the authentication token because verification keys are temporarily unavailable. Retry the request.

compute_gateway

Code	Status	Message
`compute_gateway.cloud_route_error`		Failed to resolve route from cloud.
`compute_gateway.no_route`		No route found.

config

Code	Status	Message
`config.endpoint_mismatch`		Endpoint mismatch.
`config.namespace_mismatch`		Namespace mismatch.

connection

Actor connections opened through the connection protocol.

Code	Status	Message
`connection.disconnect_failed`		Connection disconnect failed
`connection.not_configured`		Connection callback is not configured
`connection.not_found`		Connection was not found
`connection.not_hibernatable`		Connection is not hibernatable
`connection.restore_not_found`		Hibernatable connection restore target was not found

datacenter

Code	Status	Message
`datacenter.not_found`		The provided datacenter does not exist.

depot

Code	Status	Message
`depot.branch_not_reachable`		Restore point branch is not reachable from this database branch chain.
`depot.branch_not_writable`		Database branch is not writable.
`depot.bucket_fork_chain_too_deep`		Bucket branch fork chain is too deep.
`depot.cold_object_corrupt`		SQLite cold object does not match the reference that named it.
`depot.commit_too_large`		SQLite commit payload is too large.
`depot.database_not_found`		Database was not found in this bucket branch.
`depot.delta_page_missing`		SQLite delta does not carry a page it owns.
`depot.fence_mismatch`		Depot debug fence mismatch.
`depot.fork_chain_too_deep`		Database branch fork chain is too deep.
`depot.fork_out_of_retention`		Cannot fork from a point that has fallen out of retention.
`depot.head_fence_mismatch`		SQLite head fence mismatch.
`depot.invalid_policy_value`		SQLite policy value is invalid.
`depot.invalid_v1_migration_state`		Invalid SQLite v1 migration state.
`depot.meta_missing`		SQLite metadata is missing.
`depot.quota_exceeded`		Not enough space left in Depot.
`depot.restore_point_expired`		Restore point history is no longer retained.
`depot.restore_point_not_found`		Restore point was not found.
`depot.shard_cache_corrupt`		SQLite shard cache is corrupt.
`depot.shard_coverage_missing`		SQLite shard coverage is missing.
`depot.shard_version_cap_exhausted`		SQLite shard version cap is exhausted.
`depot.stage_not_found`		SQLite staged commit segment is missing.
`depot.stage_segment_invalid`		SQLite staged commit segment is invalid.
`depot.stale_main_page`		SQLite page one disagrees with the database size at its txid.
`depot.too_many_pins`		Bucket has too many restore_points.
`depot.too_many_restore_points`		Bucket has too many restore points.

engine

Code	Status	Message
`engine.binary_not_found`		Engine binary was not found.
`engine.binary_unavailable`		Engine binary is unavailable.
`engine.checksum_mismatch`		Engine binary checksum mismatch.
`engine.download_failed`		Engine binary download failed.
`engine.health_check_failed`		Engine health check failed.
`engine.invalid_endpoint`		Engine endpoint is invalid.
`engine.missing_pid`		Engine process is missing a pid.
`engine.port_occupied`		Engine port is occupied by a different runtime.

guard

The gateway that routes requests to actors, including request parsing, rate limits, and timeouts.

Code	Status	Message
`guard.actor_ready_timeout`	`503`	Timed out waiting for actor to become ready. Ensure that the pool selector is accurate and there are envoys available in the namespace you created this actor.
`guard.actor_runner_failed`		Actor's runner pool is experiencing errors.
`guard.actor_stopped_while_waiting`	`503`	Actor stopped while waiting for a response.
`guard.actor_stopped_while_waiting_for_websocket_open`		Actor stopped while waiting for WebSocket open.
`guard.actor_wake_retries_exceeded`	`503`	Actor wake retries exceeded.
`guard.connection_error`		Connection error: {error_message}.
`guard.gateway_response_start_timeout`	`504`	Timed out waiting for actor response start.
`guard.http_request_build_failed`		Failed to build HTTP request.
`guard.invalid_header`		Invalid header value.
`guard.invalid_request`		Invalid request.
`guard.invalid_request_body`	`413`	Unable to parse request body.
`guard.invalid_response_body`	`502`	Unable to parse response body.
`guard.max_in_flight`		Too many concurrent requests. Try again later.
`guard.missing_header`		Missing header required for routing.
`guard.missing_query_parameter`		Missing query parameter required for routing.
`guard.must_use_regional_host`		Request must use a regional URL for this datacenter.
`guard.no_route`	`404`	No route found.
`guard.no_route_targets`		No targets found.
`guard.query_ambiguous_runner_configs`		query gateway actor resolution found multiple runner configs for namespace
`guard.query_duplicate_param`		duplicate query gateway param
`guard.query_empty_actor_name`		query gateway actor name must not be empty
`guard.query_get_disallowed_params`		query gateway method=get does not allow rvt-input, rvt-region, rvt-crash-policy, or rvt-pool params
`guard.query_invalid_base64_input`		invalid base64url in query gateway input
`guard.query_invalid_cbor_input`		invalid query gateway input cbor
`guard.query_invalid_params`		invalid query gateway params
`guard.query_invalid_percent_encoding`		invalid percent-encoding for query gateway param
`guard.query_missing_pool`		query gateway method=getOrCreate requires rvt-pool param
`guard.query_missing_runner_name`		query gateway method=getOrCreate requires rvt-runner param
`guard.query_no_runner_configs`		query gateway actor resolution found no runner configs for namespace
`guard.query_param_missing_equals`		query gateway param is missing '='
`guard.query_path_token_syntax`		query gateway paths must not use @token syntax
`guard.query_unknown_param`		unknown query gateway param
`guard.rate_limit`	`429`	Too many requests. Try again later.
`guard.request_body_too_large`		Request body too large.
`guard.request_build_error`		Request build error.
`guard.request_delivery_unconfirmed`	`503`	Actor did not respond to request start.
`guard.request_timeout`	`504`	Request timed out.
`guard.response_body_too_large`		Response body too large.
`guard.retry_attempts_exceeded`	`502`	Retry attempts exceeded.
`guard.route_api_public_timeout`	`504`	Timed out resolving the api-public route.
`guard.route_auth_check_timeout`	`504`	Timed out checking route authorization.
`guard.route_compute_timeout`	`504`	Timed out resolving the compute gateway route.
`guard.route_dispatch_timeout`	`504`	Timed out dispatching route resolution to a routing module.
`guard.service_unavailable`	`503`	Service unavailable.
`guard.target_changed`		WebSocket target changed, retry not possible.
`guard.tunnel_message_timeout`	`504`	Actor tunnel message timed out.
`guard.tunnel_request_aborted`	`503`	Actor tunnel aborted the request.
`guard.tunnel_response_closed`	`503`	Actor tunnel closed before sending a response.
`guard.upstream_error`	`502`	Upstream error.
`guard.uri_parse_error`		URI parse error.
`guard.websocket_closed_before_open`		WebSocket closed before opening.
`guard.websocket_garbage_collected`		WebSocket request was garbage collected.
`guard.websocket_hibernation_not_supported`		The requested service does not support websocket hibernation.
`guard.websocket_not_supported`		The requested service does not support websockets.
`guard.websocket_open_dropped`		WebSocket open was dropped.
`guard.websocket_open_response_closed`		WebSocket open response closed.
`guard.websocket_open_timeout`		Timed out waiting for WebSocket open.
`guard.websocket_pending_limit_reached`		Reached limit on pending websocket messages, aborting connection.
`guard.websocket_service_hibernate`		Initiate WebSocket service hibernation.
`guard.websocket_tunnel_ping_timeout`		WebSocket tunnel ping timed out.
`guard.websocket_tunnel_subscription_closed`		WebSocket tunnel subscription closed.
`guard.wrong_addr_protocol`		Attempted to access a address using the wrong protocol.

inspector

Code	Status	Message
`inspector.invalid_request`		Invalid inspector request
`inspector.unauthorized`		Inspector request requires a valid bearer token

kv

Low-level KV storage inside an actor.

Code	Status	Message
`kv.leader_forwarding_failed`	`400`	Failed to forward request to leader.
`kv.no_leader_elected`	`400`	No leader has been elected yet.
`kv.not_leader`	`400`	Current node is not the leader.
`kv.response_channel_closed`	`400`	Failed to receive KV response, channel closed.

message

Message size limits on connections.

Code	Status	Message
`message.incoming_too_long`	`400`	Incoming message too long.
`message.outgoing_too_long`	`400`	Outgoing message too long

namespace

Namespace lookup and creation.

Code	Status	Message
`namespace.failed_to_create`		Failed to create namespace.
`namespace.invalid_update`		Failed to update namespace.
`namespace.name_not_unique`		Namespace name must be unique.
`namespace.not_found`		The namespace does not exist.
`namespace.not_leader`		Attempting to run operation in non-leader datacenter.

napi

Code	Status	Message
`napi.invalid_argument`		Invalid native argument
`napi.invalid_state`		Invalid native state

pegboard

Code	Status	Message
`pegboard.route_auth_check_timeout`	`504`	Timed out checking actor route authorization.
`pegboard.route_fetch_actor_timeout`	`504`	Timed out fetching actor routing state.
`pegboard.route_resolve_query_timeout`	`504`	Timed out resolving actor query route.
`pegboard.route_subscribe_timeout`	`504`	Timed out subscribing to actor routing events.
`pegboard.route_wake_signal_timeout`	`504`	Timed out sending actor wake signal.

protocol

Encoding and framing of connection protocol messages.

Code	Status	Message
`protocol.invalid_actor_connect_request`		Invalid actor-connect request.
`protocol.invalid_http_request`		Invalid HTTP request.
`protocol.invalid_http_response`		Invalid HTTP response.
`protocol.invalid_persisted_data`		Invalid persisted actor data.
`protocol.unsupported_encoding`		Unsupported protocol encoding.

queue

Actor queues.

Code	Status	Message
`queue.already_completed`	`400`	Queue message was already completed
`queue.complete_not_configured`	`400`	Queue message does not support completion
`queue.completion_waiter_conflict`	`400`	Queue completion waiter conflict
`queue.completion_waiter_dropped`	`400`	Queue completion waiter dropped before response
`queue.full`	`400`	Queue is full
`queue.invalid_message_key`	`400`	Queue message key is invalid
`queue.message_too_large`	`400`	Queue message is too large
`queue.timed_out`	`400`	Queue wait timed out

registry

Code	Status	Message
`registry.shut_down`		Registry is shut down.

request

Code	Status	Message
`request.invalid`		Invalid request.

runner

Code	Status	Message
`runner.not_found`		The runner does not exist.

runner_config

Code	Status	Message
`runner_config.invalid`		Invalid runner config.
`runner_config.not_found`		No config for this runner exists.

serverless_runner_pool

Code	Status	Message
`serverless_runner_pool.failed_to_fetch_metadata`		Failed to fetch serverless metadata: {reason}.
`serverless_runner_pool.not_found`		No serverless pool for this runner exists.

sqlite

Code	Status	Message
`sqlite.closed`		SQLite database is closed.
`sqlite.invalid_bind_parameter`		Invalid SQLite bind parameter.
`sqlite.not_configured`		SQLite is not configured.
`sqlite.remote_execution_failed`		Remote SQLite execution failed.
`sqlite.remote_fence_mismatch`		Remote SQLite generation is stale.
`sqlite.remote_indeterminate_result`		Remote SQLite result is indeterminate.
`sqlite.remote_unavailable`		Remote SQLite is unavailable.
`sqlite.unavailable`		SQLite is unavailable.

ups

Code	Status	Message
`ups.publish_failed`		Failed to publish message after retries
`ups.request_timeout`		Request timeout.

user

Errors thrown by your actor code. The code is whatever you pass to UserError.

validation

Request validation.

Code	Status	Message
`validation.invalid_input`		Invalid input provided
`validation.no_keys`		No keys provided. At least one key is required.
`validation.race_condition`		Race condition detected
`validation.too_many_actor_ids`		Too many actor IDs provided

wasm

Code	Status	Message
`wasm.invalid_config`		Invalid wasm configuration.
`wasm.invalid_state`		Invalid wasm state

ws

WebSocket handling for the connection protocol and onWebSocket handlers.

Code	Status	Message
`ws.connection_closed`		Normal connection close.
`ws.eviction`		The websocket has been evicted and should not attempt to reconnect.
`ws.going_away`		The Rivet Engine is migrating. The websocket should attempt to reconnect as soon as possible.
`ws.invalid_initial_packet`		The websocket could not process the initial packet.
`ws.invalid_packet`		The websocket could not process the given packet.
`ws.invalid_request`		The websocket could not open due to an invalid request.
`ws.invalid_url`		The connection URL is invalid.
`ws.no_runner_config`		Must create a runner config before connecting an envoy with pool name {pool_name:?}.
`ws.registration_expired`		The envoy registration expired while its connection was still active. The websocket should reconnect.
`ws.timed_out`		Ping timed out.
`ws.timed_out_waiting_for_init`		Timed out waiting for the init packet to be sent.