This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Error codes

Error codes and messages you may encounter while using Dapr

1 - Errors overview

Overview of Dapr errors

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

Note: See a full list of error codes in Dapr.

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 codes

2 - Error codes reference guide

List of gRPC and HTTP error codes in Dapr and their descriptions

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

Detailed reference of the Dapr HTTP error codes and how to handle them

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."
}

4 - Handling gRPC error codes

Information on Dapr gRPC errors and how to handle them

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.

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.