runtime-errors.md

Carrier Runtime Errors

This file lists the runtime-reserved code values emitted by Carrier itself. Application-level fail(code, message) codes are owned by the application and are not reserved by the language.

Stable Top-Level Codes

Code	Status	Meaning	Typical remediation
validation_failed	400	A request field failed built-in validation.	Inspect details[] and fix the request payload/query/path value.
missing_idempotency_key	400	An idempotent route was called without Idempotency-Key.	Send a non-empty Idempotency-Key header.
int_overflow	400	Checked Int arithmetic exceeded the i64 range.	Bound the inputs or use smaller intermediate values.
division_by_zero	400	Int division used a zero divisor.	Guard the divisor before dividing.
invalid_random_range	400	random.int(...) or random.float(...) received invalid bounds.	Ensure integer min <= max; ensure float bounds are finite and min < max.
empty_random_choice	400	random.choice(...) received an empty list.	Guard the list length or provide a fallback before choosing.
invalid_id_length	400	id.opaque(...), id.nanoid(...), crypto.random_bytes(...), or crypto.token(bytes: ...) received a non-positive length.	Pass a positive byte count or string length.
invalid_crypto_signature	400	crypto.verify_hmac_sha256(...) received malformed hex signature input.	Pass an even-length hex signature string from the webhook provider.
invalid_transport	400	A realtime transport selection was not one of the supported values.	Use websocket, sse, or long_polling.
invalid_llm_client	400	An llm client declaration compiled, but the runtime config was incomplete.	Set a non-empty API key and model for the configured LLM client.
unsupported_llm_provider	400	The configured llm client wire format is not supported by the runtime.	Set wire_format to openai or anthropic, and use base_url/api_path for compatible providers.
llm_budget_requires_tenant	400	A budgeted llm client call ran without a tenant-scoped caller.	Call the client from tenant-scoped context or remove the tenant budget.
llm_budget_exceeded	400	A budgeted llm client exhausted its tenant budget and the configured behavior was fail.	Increase the budget, wait for the next window, or configure a downgrade client.
unknown_llm_model_pricing	400	Budget enforcement could not price the configured provider/model pair.	Use a model with built-in pricing support or update Carrier’s pricing table.
invalid_analytics_dp_policy	400	A differential-privacy policy used invalid epsilon/delta/budget/contribution settings.	Use finite positive epsilon values, non-negative delta values, and a budget at least as large as one release.
invalid_analytics_dp_request	400	A runtime DP budget request omitted required analytics, scope, or query identifiers.	Provide non-empty analytics_name, scope_key, and query_signature values.
invalid_analytics_dp_noise_request	400	A DP noise helper received invalid sensitivity/epsilon/delta inputs.	Use finite inputs, positive sensitivity, positive epsilon, and a non-negative delta; gaussian noise requires delta > 0.
invalid_llm_tool_input	400	An LLM tool call payload did not match the generated Carrier tool schema.	Ensure the tool arguments are a JSON object with the documented fields and types.
invalid_vector_dimension	400	A Vector(N) value had the wrong dimension at runtime.	Send or return a vector with exactly the declared number of elements.
invalid_similarity_limit	400	A generated vector search helper received a non-positive limit.	Pass an Int greater than zero.
invalid_hybrid_query	400	Model.hybrid_search(...) received an empty text query.	Pass a non-empty query string for the full-text side of the search.
invalid_job_payload	400	A queued job payload did not match the generated input type.	Enqueue the documented payload shape for that job.
unknown_job	400	The worker received a job name the generated dispatcher does not know.	Ensure job names come from the current compiled project.
invalid_scope	400	A CRUD scope string was not one of Carrier's supported scopes.	Use active, all, or deleted where applicable.
invalid_sort_direction	400	A CRUD direction value was not asc or desc.	Send asc or desc.
invalid_sort	400	A requested sort field is not allowed for that CRUD endpoint.	Use one of the documented sort fields.
invalid_overlap_filter	400	A range-overlap filter request was incomplete or invalid.	Provide both overlap endpoints with compatible values.
missing_version	400	An optimistic-locking update omitted the required @version field.	Include the current record version in the update body.
index_out_of_bounds	400	A list index was negative or outside the list length.	Guard the index before indexing.
invalid_json	400	json.parse(...) failed to decode the provided string.	Pass valid JSON text.
invalid_json_path	400	json.path(...), json.path_first(...), or json.exists(...) received malformed path syntax.	Start with $ and use only .field, [index], and [*].
invalid_fhir_resource_type	400	healthcare.fhir_resource(...) or healthcare.fhir_reference(...) received an empty FHIR resource type.	Pass a non-empty resource type such as Patient or Observation.
invalid_fhir_resource	400	healthcare.fhir_resource(...) received a non-object payload, a mismatched resourceType, or an invalid/missing resource identifier where one was required.	Pass a JSON object and keep resourceType/id aligned with the helper arguments.
invalid_fhir_reference	400	healthcare.fhir_reference(...) or healthcare.fhir_resolve_reference(...) received an invalid reference payload.	Pass a non-empty resourceType and id, or a reference object with a non-empty reference string.
invalid_fhir_bundle	400	healthcare.fhir_bundle(...) or healthcare.fhir_resolve_reference(...) received an invalid Bundle payload.	Pass a Bundle object with resourceType: "Bundle" and an entry array, or pass Json[] resources/entries to the bundle helper.
invalid_fhir_bundle_entry	400	healthcare.fhir_bundle(...) received an item that was neither a resource object nor an entry object with resource.	Pass resource JSON objects directly or pass entry objects that include a valid resource field.
invalid_tax_rate	400	finance.tax_exclusive(...), finance.tax_inclusive(...), or finance.withholding(...) received a negative rate.	Pass a non-negative decimal fraction such as 0.07 or 0.24.
invalid_pdf_content	400	A pdf.* helper received empty content or content that could not be parsed into a PDF payload.	Pass non-empty HTML or SVG template content and keep the rendered output structurally valid.
invalid_pdf_destination	400	A pdf.* helper received an empty destination path.	Pass a non-empty server-side output path such as /tmp/invoices/invoice-42.pdf.
invalid_pdf_font	400	pdf.render_svg_template(...) failed to load a requested custom font file.	Pass existing .ttf/.otf files in font_paths, or omit the option when system fonts are sufficient.
invalid_image_path	400	image.* received an empty source or inspect path.	Pass a non-empty server-side input path such as /tmp/uploads/photo.jpg.
invalid_image_destination	400	image.* received an empty destination path.	Pass a non-empty server-side output path such as /tmp/uploads/avatar.webp.
invalid_image_content	400	image.* could not recognize or decode the provided image file.	Pass a valid image file and verify the upload completed before processing.
invalid_image_dimensions	400	image.* received non-positive or otherwise invalid size/crop arguments.	Use positive width/height values and non-negative crop coordinates.
image_crop_out_of_bounds	400	image.crop(...) requested a rectangle outside the source image bounds.	Inspect the source dimensions first with image.metadata(...) and crop within that range.
unsupported_image_format	400	image.* was asked to encode an unsupported output format.	Use jpeg, png, or webp.
image_too_large	400	image.* input exceeded the runtime byte limit.	Keep source images under the documented input-size bound before processing.
image_processing_bounds	400	image.* input or output exceeded the runtime dimension/pixel limits.	Keep images within the documented max dimensions and total pixel count.
image_encode_failed	400	image.* failed while encoding the processed output image.	Retry with a supported output format and valid destination path.
invalid_blob_key	400	A blob.* helper received an empty key or a path-traversal-like key.	Use normalized forward-slash blob keys such as exports/report.pdf.
invalid_blob_expiry	400	blob.signed_url(...) received an invalid expiry for the active backend.	Pass a positive expires_seconds value.
blob_url_expired	400	A local Carrier blob signed URL was used after its expiry timestamp.	Request a fresh signed URL and retry before it expires.
unsupported_blob_method	400	blob.signed_url(...) requested an unsupported method for the active backend.	Use GET for local storage; use GET or PUT for S3-backed storage.
invalid_mobile_file_checksum	400	A generated Mobile Mode file endpoint received a malformed SHA-256 checksum.	Send a 64-character hexadecimal SHA-256 digest for staged and committed files.
mobile_file_checksum_mismatch	400	A generated Mobile Mode file commit found that the uploaded object checksum did not match the staged checksum.	Re-upload the object for the same staged upload or start a new upload with the correct checksum.
invalid_mobile_file_upload	400	A generated Mobile Mode file stage request was missing a valid upload id.	Generate a stable retry-safe upload id before calling the stage endpoint.
invalid_mobile_file_size	400	A generated Mobile Mode file stage request used a negative size.	Send the non-negative byte length of the local file.
invalid_base64	400	base64.decode(...) received malformed input or bytes that were not valid UTF-8 text.	Pass standard base64 text with valid padding that decodes to UTF-8.
invalid_base64url	400	base64url.decode(...) received malformed input or bytes that were not valid UTF-8 text.	Pass URL-safe base64 text with optional padding that decodes to UTF-8.
invalid_hex	400	hex.decode(...) received malformed input or bytes that were not valid UTF-8 text.	Pass even-length hexadecimal text that decodes to UTF-8.
invalid_url	400	url.parse(...) received malformed absolute or relative URL input.	Pass a valid absolute URL such as https://api.example.com/path or a valid relative reference such as /hooks/callback?topic=lab.
invalid_url_encoding	400	url.decode(...) received malformed percent-encoding or bytes that were not valid UTF-8 text.	Pass percent-encoded UTF-8 text with complete %HH escapes.
unauthorized	401	Authentication failed or the request did not carry a valid access token.	Supply a valid bearer token or re-authenticate.
forbidden	403	The authenticated user did not satisfy the guard's role requirement.	For roles [...], use a token with any listed role. For all_roles [...], use a token with every listed role.
not_found	404	The requested record, cache entry, or realtime stream does not exist.	Check the identifier/path and current data state.
conflict	409	The operation conflicts with current state.	Retry with fresh state or a different identifier.
upstream_error	502	A generated HTTP client failed or the upstream returned an invalid response.	Retry if safe or inspect the upstream dependency.
invalid_email	400	email.send(...) received an invalid mailbox or missing body.	Validate to, from, cc, bcc, reply_to, and provide text or html.
email_transport_missing	503	email.send(...) could not find SMTP_URL and no smtp_url argument was provided.	Configure SMTP_URL or use smtp_url: "sink://local" for local/CI runs.
invalid_email_transport	503	The configured SMTP URL could not be parsed.	Use a valid smtp://... or smtps://... URL.
CARRIER_DEPTH_LIMIT_EXCEEDED	400/422/500	A request body, schema/ref expansion, route chain, action chain, workflow/expression chain, or overall Carrier execution chain exceeded its configured depth limit.	Inspect limit, location, and hint; look for recursive route/action/workflow calls or overly deep JSON/schema input.
CARRIER_RUNTIME_PANIC	500	Carrier caught a generated runtime panic and converted it into a structured error/evidence bundle.	Inspect the emitted evidence bundle, especially stack_hash, panic_message, route/action metadata, and suggested_test.
internal_error	500	Carrier hit an internal runtime or serialization/configuration error.	Inspect logs and runtime status; fix configuration or report a bug.

Validation Detail Codes

validation_failed responses may include these stable details[].code values:

• invalid_email
• min_length
• max_length
• pattern
• min_value
• max_value

Test-Only Codes

Carrier test blocks can also emit these generated test harness codes:

• invalid_test_header
• invalid_test_method
• invalid_test_headers
• invalid_test_path
• unexpected_test_response
• invalid_test_response_body
• test_assertion_failed

These codes are stable for the generated test harness, but they do not appear in production HTTP traffic unless the application deliberately exposes the test harness.