This is the multi-page printable view of this section. Click here to print.
Error codes
- 1: Errors overview
- 2: Error codes reference guide
- 3: Handling HTTP error codes
- 4: Handling gRPC error codes
1 - Errors overview
An error code is a numeric or alphamueric code that indicates the nature of an error and, when possible, why it occured.
Dapr error codes are standardized strings for over 80+ common errors across HTTP and gRPC requests when using the Dapr APIs. These codes are both:
- Returned in the JSON response body of the request.
- When enabled, logged in debug-level logs in the runtime.
- If you’re running in Kubernetes, error codes are logged in the sidecar.
- If you’re running in self-hosted, you can enable and run debug logs.
Error format
Dapr error codes consist of a prefix, a category, and shorthand of the error itself. For example:
Prefix | Category | Error shorthand |
---|---|---|
ERR_ | PUBSUB_ | NOT_FOUND |
Some of the most common errors returned include:
- ERR_ACTOR_TIMER_CREATE
- ERR_PURGE_WORKFLOW
- ERR_STATE_STORE_NOT_FOUND
- ERR_HEALTH_NOT_READY
An error returned for a state store not found might look like the following:
{
"error": "Bad Request",
"error_msg": "{\"errorCode\":\"ERR_STATE_STORE_NOT_FOUND\",\"message\":\"state store <name> is not found\",\"details\":[{\"@type\":\"type.googleapis.com/google.rpc.ErrorInfo\",\"domain\":\"dapr.io\",\"metadata\":{\"appID\":\"nodeapp\"},\"reason\":\"DAPR_STATE_NOT_FOUND\"}]}",
"status": 400
}
The returned error includes:
- The error code:
ERR_STATE_STORE_NOT_FOUND
- The error message describing the issue:
state store <name> is not found
- The app ID in which the error is occuring:
nodeapp
- The reason for the error:
DAPR_STATE_NOT_FOUND
Dapr error code metrics
Metrics help you see when exactly errors are occuring from within the runtime. Error code metrics are collected using the error_code_total
endpoint. This endpoint is disabled by default. You can enable it using the recordErrorCodes
field in your configuration file.
Demo
Watch a demo presented during Diagrid’s Dapr v1.15 celebration to see how to enable error code metrics and handle error codes returned in the runtime.
Next step
See a list of all Dapr error codes2 - Error codes reference guide
The following tables list the error codes returned by Dapr runtime.
The error codes are returned in the response body of an HTTP request or in the ErrorInfo
section of a gRPC status response, if one is present.
An effort is underway to enrich all gRPC error responses according to the Richer Error Model. Error codes without a corresponding gRPC code indicate those errors have not yet been updated to this model.
Actors API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_ACTOR_INSTANCE_MISSING |
Missing actor instance | |
ERR_ACTOR_INVOKE_METHOD |
Error invoking actor method | |
ERR_ACTOR_RUNTIME_NOT_FOUND |
Actor runtime not found | |
ERR_ACTOR_STATE_GET |
Error getting actor state | |
ERR_ACTOR_STATE_TRANSACTION_SAVE |
Error saving actor transaction | |
ERR_ACTOR_REMINDER_CREATE |
Error creating actor reminder | |
ERR_ACTOR_REMINDER_DELETE |
Error deleting actor reminder | |
ERR_ACTOR_REMINDER_GET |
Error getting actor reminder | |
ERR_ACTOR_REMINDER_NON_HOSTED |
Reminder operation on non-hosted actor type | |
ERR_ACTOR_TIMER_CREATE |
Error creating actor timer | |
ERR_ACTOR_NO_APP_CHANNEL |
App channel not initialized | |
ERR_ACTOR_STACK_DEPTH |
Maximum actor call stack depth exceeded | |
ERR_ACTOR_NO_PLACEMENT |
Placement service not configured | |
ERR_ACTOR_RUNTIME_CLOSED |
Actor runtime is closed | |
ERR_ACTOR_NAMESPACE_REQUIRED |
Actors must have a namespace configured when running in Kubernetes mode | |
ERR_ACTOR_NO_ADDRESS |
No address found for actor |
Workflows API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_GET_WORKFLOW |
Error getting workflow | |
ERR_START_WORKFLOW |
Error starting workflow | |
ERR_PAUSE_WORKFLOW |
Error pausing workflow | |
ERR_RESUME_WORKFLOW |
Error resuming workflow | |
ERR_TERMINATE_WORKFLOW |
Error terminating workflow | |
ERR_PURGE_WORKFLOW |
Error purging workflow | |
ERR_RAISE_EVENT_WORKFLOW |
Error raising event in workflow | |
ERR_WORKFLOW_COMPONENT_MISSING |
Missing workflow component | |
ERR_WORKFLOW_COMPONENT_NOT_FOUND |
Workflow component not found | |
ERR_WORKFLOW_EVENT_NAME_MISSING |
Missing workflow event name | |
ERR_WORKFLOW_NAME_MISSING |
Workflow name not configured | |
ERR_INSTANCE_ID_INVALID |
Invalid workflow instance ID. (Only alphanumeric and underscore characters are allowed) | |
ERR_INSTANCE_ID_NOT_FOUND |
Workflow instance ID not found | |
ERR_INSTANCE_ID_PROVIDED_MISSING |
Missing workflow instance ID | |
ERR_INSTANCE_ID_TOO_LONG |
Workflow instance ID too long |
State management API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_STATE_TRANSACTION |
Error in state transaction | |
ERR_STATE_SAVE |
Error saving state | |
ERR_STATE_GET |
Error getting state | |
ERR_STATE_DELETE |
Error deleting state | |
ERR_STATE_BULK_DELETE |
Error deleting state in bulk | |
ERR_STATE_BULK_GET |
Error getting state in bulk | |
ERR_NOT_SUPPORTED_STATE_OPERATION |
Operation not supported in transaction | |
ERR_STATE_QUERY |
DAPR_STATE_QUERY_FAILED |
Error querying state |
ERR_STATE_STORE_NOT_FOUND |
DAPR_STATE_NOT_FOUND |
State store not found |
ERR_STATE_STORE_NOT_CONFIGURED |
DAPR_STATE_NOT_CONFIGURED |
State store not configured |
ERR_STATE_STORE_NOT_SUPPORTED |
DAPR_STATE_TRANSACTIONS_NOT_SUPPORTED |
State store does not support transactions |
ERR_STATE_STORE_NOT_SUPPORTED |
DAPR_STATE_QUERYING_NOT_SUPPORTED |
State store does not support querying |
ERR_STATE_STORE_TOO_MANY_TRANSACTIONS |
DAPR_STATE_TOO_MANY_TRANSACTIONS |
Too many operations per transaction |
ERR_MALFORMED_REQUEST |
DAPR_STATE_ILLEGAL_KEY |
Invalid key |
Configuration API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_CONFIGURATION_GET |
Error getting configuration | |
ERR_CONFIGURATION_STORE_NOT_CONFIGURED |
Configuration store not configured | |
ERR_CONFIGURATION_STORE_NOT_FOUND |
Configuration store not found | |
ERR_CONFIGURATION_SUBSCRIBE |
Error subscribing to configuration | |
ERR_CONFIGURATION_UNSUBSCRIBE |
Error unsubscribing from configuration |
Crypto API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_CRYPTO |
Error in crypto operation | |
ERR_CRYPTO_KEY |
Error retrieving crypto key | |
ERR_CRYPTO_PROVIDER_NOT_FOUND |
Crypto provider not found | |
ERR_CRYPTO_PROVIDERS_NOT_CONFIGURED |
Crypto providers not configured |
Secrets API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_SECRET_GET |
Error getting secret | |
ERR_SECRET_STORE_NOT_FOUND |
Secret store not found | |
ERR_SECRET_STORES_NOT_CONFIGURED |
Secret store not configured | |
ERR_PERMISSION_DENIED |
Permission denied by policy |
Pub/Sub and messaging errors
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_PUBSUB_EMPTY |
DAPR_PUBSUB_NAME_EMPTY |
Pubsub name is empty |
ERR_PUBSUB_NOT_FOUND |
DAPR_PUBSUB_NOT_FOUND |
Pubsub not found |
ERR_PUBSUB_NOT_FOUND |
DAPR_PUBSUB_TEST_NOT_FOUND |
Pubsub not found |
ERR_PUBSUB_NOT_CONFIGURED |
DAPR_PUBSUB_NOT_CONFIGURED |
Pubsub not configured |
ERR_TOPIC_NAME_EMPTY |
DAPR_PUBSUB_TOPIC_NAME_EMPTY |
Topic name is empty |
ERR_PUBSUB_FORBIDDEN |
DAPR_PUBSUB_FORBIDDEN |
Access to topic forbidden for APP ID |
ERR_PUBSUB_PUBLISH_MESSAGE |
DAPR_PUBSUB_PUBLISH_MESSAGE |
Error publishing message |
ERR_PUBSUB_REQUEST_METADATA |
DAPR_PUBSUB_METADATA_DESERIALIZATION |
Error deserializing metadata |
ERR_PUBSUB_CLOUD_EVENTS_SER |
DAPR_PUBSUB_CLOUD_EVENT_CREATION |
Error creating CloudEvent |
ERR_PUBSUB_EVENTS_SER |
DAPR_PUBSUB_MARSHAL_ENVELOPE |
Error marshalling Cloud Event envelope |
ERR_PUBSUB_EVENTS_SER |
DAPR_PUBSUB_MARSHAL_EVENTS |
Error marshalling events to bytes |
ERR_PUBSUB_EVENTS_SER |
DAPR_PUBSUB_UNMARSHAL_EVENTS |
Error unmarshalling events |
ERR_PUBLISH_OUTBOX |
Error publishing message to outbox |
Conversation API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_CONVERSATION_INVALID_PARMS |
Invalid parameters for conversation component | |
ERR_CONVERSATION_INVOKE |
Error invoking conversation | |
ERR_CONVERSATION_MISSING_INPUTS |
Missing inputs for conversation | |
ERR_CONVERSATION_NOT_FOUND |
Conversation not found |
Service Invocation / Direct Messaging API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_DIRECT_INVOKE |
Error invoking service |
Bindings API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_INVOKE_OUTPUT_BINDING |
Error invoking output binding |
Distributed Lock API
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_LOCK_STORE_NOT_CONFIGURED |
Lock store not configured | |
ERR_LOCK_STORE_NOT_FOUND |
Lock store not found | |
ERR_TRY_LOCK |
Error acquiring lock | |
ERR_UNLOCK |
Error releasing lock |
Healthz
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_HEALTH_NOT_READY |
Dapr not ready | |
ERR_HEALTH_APPID_NOT_MATCH |
Dapr App ID does not match | |
ERR_OUTBOUND_HEALTH_NOT_READY |
Dapr outbound not ready |
Common
HTTP Code | gRPC Code | Description |
---|---|---|
ERR_API_UNIMPLEMENTED |
API not implemented | |
ERR_APP_CHANNEL_NIL |
App channel is nil | |
ERR_BAD_REQUEST |
Bad request | |
ERR_BODY_READ |
Error reading request body | |
ERR_INTERNAL |
Internal error | |
ERR_MALFORMED_REQUEST |
Malformed request | |
ERR_MALFORMED_REQUEST_DATA |
Malformed request data | |
ERR_MALFORMED_RESPONSE |
Malformed response |
Scheduler/Jobs API
HTTP Code | gRPC Code | Description |
---|---|---|
DAPR_SCHEDULER_SCHEDULE_JOB |
DAPR_SCHEDULER_SCHEDULE_JOB |
Error scheduling job |
DAPR_SCHEDULER_JOB_NAME |
DAPR_SCHEDULER_JOB_NAME |
Job name should only be set in the url |
DAPR_SCHEDULER_JOB_NAME_EMPTY |
DAPR_SCHEDULER_JOB_NAME_EMPTY |
Job name is empty |
DAPR_SCHEDULER_GET_JOB |
DAPR_SCHEDULER_GET_JOB |
Error getting job |
DAPR_SCHEDULER_LIST_JOBS |
DAPR_SCHEDULER_LIST_JOBS |
Error listing jobs |
DAPR_SCHEDULER_DELETE_JOB |
DAPR_SCHEDULER_DELETE_JOB |
Error deleting job |
DAPR_SCHEDULER_EMPTY |
DAPR_SCHEDULER_EMPTY |
Required argument is empty |
DAPR_SCHEDULER_SCHEDULE_EMPTY |
DAPR_SCHEDULER_SCHEDULE_EMPTY |
No schedule provided for job |
Generic
HTTP Code | gRPC Code | Description |
---|---|---|
ERROR |
ERROR |
Generic error |
Next steps
3 - Handling HTTP error codes
For HTTP calls made to Dapr runtime, when an error is encountered, an error JSON is returned in response body. The JSON contains an error code and an descriptive error message.
{
"errorCode": "ERR_STATE_GET",
"message": "Requested state key does not exist in state store."
}
Related
4 - Handling gRPC error codes
Initially, errors followed the Standard gRPC error model. However, to provide more detailed and informative error messages, an enhanced error model has been defined which aligns with the gRPC Richer error model.
Note
Not all Dapr errors have been converted to the richer gRPC error model.Standard gRPC Error Model
The Standard gRPC error model is an approach to error reporting in gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions.
Example of a Standard gRPC Error Response:
ERROR:
Code: InvalidArgument
Message: input key/keyPrefix 'bad||keyname' can't contain '||'
Richer gRPC Error Model
The Richer gRPC error model extends the standard error model by providing additional context and details about the error. This model includes the standard error code
and message
, along with a details
section that can contain various types of information, such as ErrorInfo
, ResourceInfo
, and BadRequest
details.
Example of a Richer gRPC Error Response:
ERROR:
Code: InvalidArgument
Message: input key/keyPrefix 'bad||keyname' can't contain '||'
Details:
1) {
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"domain": "dapr.io",
"reason": "DAPR_STATE_ILLEGAL_KEY"
}
2) {
"@type": "type.googleapis.com/google.rpc.ResourceInfo",
"resourceName": "statestore",
"resourceType": "state"
}
3) {
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "bad||keyname",
"description": "input key/keyPrefix 'bad||keyname' can't contain '||'"
}
]
}
For HTTP clients, Dapr translates the gRPC error model to a similar structure in JSON format. The response includes an errorCode
, a message
, and a details
array that mirrors the structure found in the richer gRPC model.
Example of an HTTP error response:
{
"errorCode": "ERR_MALFORMED_REQUEST",
"message": "api error: code = InvalidArgument desc = input key/keyPrefix 'bad||keyname' can't contain '||'",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"domain": "dapr.io",
"metadata": null,
"reason": "DAPR_STATE_ILLEGAL_KEY"
},
{
"@type": "type.googleapis.com/google.rpc.ResourceInfo",
"description": "",
"owner": "",
"resource_name": "statestore",
"resource_type": "state"
},
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"field_violations": [
{
"field": "bad||keyname",
"description": "api error: code = InvalidArgument desc = input key/keyPrefix 'bad||keyname' can't contain '||'"
}
]
}
]
}
You can find the specification of all the possible status details here.