Dapr Python SDK

Common errors

• grpc.RpcError: StatusCode.UNAVAILABLE: Dapr sidecar unavailable

  cause The Dapr sidecar (`daprd`) is not running, not reachable, or has not fully initialized before the application attempts to connect. This can also manifest as `Connection refused` errors.
  fix Ensure the Dapr sidecar is properly launched alongside your application (e.g., using `dapr run`). Verify the Dapr HTTP and gRPC ports are correct and not blocked. Check Dapr sidecar logs for initialization issues.

• Error component X cannot be found

  cause A Dapr component (e.g., state store, pub/sub broker) specified in your application or code is not correctly defined, accessible, or deployed. This could be due to a missing component YAML file, incorrect `resources-path` in `dapr run`, or namespace mismatch in Kubernetes.
  fix Verify that your component YAML files are correctly placed and configured. Ensure the `dapr run` command includes the `--resources-path` argument pointing to your components directory. Check the component's name in your code matches the component's `name` field in its YAML definition.

• I'm getting 500 Error responses when calling Dapr

  cause A generic Dapr API error, often indicating an issue with the underlying component (e.g., state store database down) or a misconfiguration within Dapr itself that prevents it from fulfilling the request.
  fix Inspect the Dapr sidecar logs (enable debug logging for more details) and your application logs. The Dapr API response often includes an `errorCode` and `message` that provides specific context (e.g., `ERR_STATE_STORE_NOT_FOUND`, `ERR_PUBSUB_PUBLISH_MESSAGE`).

Warnings

• breaking Major versions of the Dapr Python SDK (e.g., 1.x to 2.x) may introduce breaking API changes, including method signature changes, module path renames, or response object field renames.
  Fix: Always check the SDK changelog and Dapr runtime release notes for breaking changes before upgrading. Test SDK upgrades in development environments first.
• deprecated Dapr's gRPC service invocation is deprecated in favor of gRPC proxying. Direct gRPC invocation via the SDK may be removed in future releases.
  Fix: When performing service invocation, prefer HTTP or gRPC proxying where applicable. Refer to the Dapr documentation for the recommended approach to gRPC communication between services.
• deprecated The `DaprClient().wait()` method is deprecated. The automatic outbound health check covers this use case upon client initialization.
  Fix: Remove explicit calls to `DaprClient().wait()`. The client will automatically perform a health check against the Dapr sidecar at initialization.
• gotcha Dapr SDK versions must be compatible with the Dapr runtime version. Mismatched versions can lead to subtle failures or unexpected behavior due to API discrepancies.
  Fix: Consult the Dapr documentation for the SDK to runtime compatibility matrix. Pin your Dapr SDK version explicitly in your `requirements.txt` (e.g., `dapr==1.17.4`) and ensure your Dapr runtime is within the supported range.
• gotcha Alpha and Preview features in Dapr and its SDKs are subject to change between releases, potentially without strict deprecation cycles.
  Fix: Exercise caution when using Alpha or Preview features in production. Be prepared for rapid changes and frequent updates to your code when new Dapr releases become available. Monitor Dapr release notes closely for updates on these features.

Install

• pip install dapr Stable release
• pip install dapr-ext-grpc dapr-ext-fastapi dapr-ext-flask dapr-ext-workflow Optional Extensions

Imports

• DaprClient

  from dapr.clients import DaprClient

• ActorInterface

  from dapr.actor import ActorInterface

  Used for defining Dapr Virtual Actors.
• DaprInternalError

  from dapr.clients.exceptions import DaprInternalError

  Essential for catching Dapr-specific client errors.

Quickstart

This quickstart demonstrates how to initialize the Dapr Python client and interact with the Dapr state management building block to save and retrieve a key-value pair. Ensure a Dapr sidecar is running and a state store component (e.g., 'statestore') is configured and accessible to your application.

import os
from dapr.clients import DaprClient

STATE_STORE_NAME = os.environ.get('STATE_STORE_NAME', 'statestore')

def main():
    with DaprClient() as client:
        key = 'my_key'
        value = 'my_value'

        # Save state
        print(f"Saving state: key={key}, value={value}")
        client.save_state(
            store_name=STATE_STORE_NAME,
            key=key,
            value=value
        )
        print("State saved successfully.")

        # Get state
        print(f"Getting state for key: {key}")
        response = client.get_state(
            store_name=STATE_STORE_NAME,
            key=key
        )
        retrieved_value = response.data.decode('utf-8')
        print(f"Retrieved state: value={retrieved_value}")

        assert retrieved_value == value
        print("State retrieval verified.")

if __name__ == '__main__':
    # Make sure a Dapr sidecar is running (e.g., `dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 python your_script.py`)
    # and a state store component named 'statestore' is configured.
    main()