DAPR Troubleshooter

This skill proactively detects DAPR issues and provides immediate solutions based on error patterns and common problems.

When to Use

Claude automatically uses this skill when:

• Error messages contain DAPR-related keywords
• Application fails to connect to DAPR sidecar
• Service invocation returns errors
• State or pub/sub operations fail
• Deployment or startup issues occur

Error Pattern Detection

Connection Errors

Pattern: connection refused, dial tcp, sidecar not ready

Error: connection refused to localhost:3500

Diagnosis:

• DAPR sidecar is not running
• Wrong DAPR port configured
• Application started before sidecar

Solutions:

1. Verify DAPR is running: dapr list
2. Check sidecar health: curl http://localhost:3500/v1.0/healthz
3. Start with DAPR: dapr run --app-id myapp -- python main.py
4. In Kubernetes, check sidecar injection: kubectl get pod -o yaml | grep dapr

Service Invocation Errors

Pattern: 404 Not Found, app-id not found, method not found

Error: ERR_DIRECT_INVOKE: app id order-service not found

Diagnosis:

• Target service not running
• App-id mismatch (case-sensitive)
• Service not registered with DAPR

Solutions:

1. Verify target is running: dapr list
2. Check exact app-id (case-sensitive)
3. Ensure target has DAPR sidecar enabled
4. Check network connectivity between services

State Store Errors

Pattern: state store not found, failed to save state, ERR_STATE

Error: state store statestore is not found

Diagnosis:

• State store component not configured
• Component name mismatch
• Backend service unavailable
• Authentication failure

Solutions:

1. Check component exists: ls ./components/
2. Verify component name matches code
3. Test backend connection (Redis, Cosmos, etc.)
4. Check secrets are accessible

Pub/Sub Errors

Pattern: pubsub not found, failed to publish, subscription error

Error: pubsub pubsub is not configured

Diagnosis:

• Pub/sub component not configured
• Topic name mismatch
• Subscriber endpoint not registered
• Message handler error

Solutions:

1. Verify pubsub component exists
2. Check topic names match exactly
3. Ensure subscription route is registered
4. Return proper response from handler: {"status": "SUCCESS"}

Component Configuration Errors

Pattern: failed to init component, component error, invalid configuration

Error: error initializing component statestore: connection refused

Diagnosis:

• Invalid component YAML
• Backend service not running
• Wrong credentials/connection string
• Missing required metadata

Solutions:

1. Validate YAML syntax
2. Start backend (Redis, etc.): docker run -d -p 6379:6379 redis
3. Check connection string/credentials
4. Verify all required metadata fields

Workflow Errors

Pattern: workflow not found, activity failed, workflow timeout

Error: workflow order_workflow not found

Diagnosis:

• Workflow runtime not started
• Workflow not registered
• Activity not registered
• State store not configured

Solutions:

1. Ensure wf_runtime.start() is called
2. Check workflow is decorated with @wf_runtime.workflow
3. Verify activities are registered
4. Configure state store for workflow persistence

Diagnostic Commands

Check DAPR Installation

dapr --version
dapr status

List Running Applications

dapr list

View DAPR Logs

# Local
dapr logs --app-id myapp

# Kubernetes
kubectl logs deployment/myapp -c daprd

Test Sidecar Health

curl http://localhost:3500/v1.0/healthz

Check Loaded Components

curl http://localhost:3500/v1.0/metadata

Test Service Invocation

curl http://localhost:3500/v1.0/invoke/target-app/method/health

Test State Store

# Save state
curl -X POST http://localhost:3500/v1.0/state/statestore \
  -H "Content-Type: application/json" \
  -d '[{"key":"test","value":"hello"}]'

# Get state
curl http://localhost:3500/v1.0/state/statestore/test

Test Pub/Sub

curl -X POST http://localhost:3500/v1.0/publish/pubsub/test-topic \
  -H "Content-Type: application/json" \
  -d '{"message":"test"}'

Common Fixes Quick Reference

Error	Quick Fix
Sidecar not running	dapr run --app-id myapp -- python main.py
Redis not running	docker run -d -p 6379:6379 redis
Component not found	Check component file in ./components/
App-id not found	Verify target app is running with dapr list
404 on invoke	Check method path and HTTP verb
Pub/sub not delivering	Return {"status": "SUCCESS"} from handler
Secret not found	Configure secret store component
State save failed	Check state store backend is running
Workflow not starting	Call wf_runtime.start()

Environment Checklist

Run this checklist when troubleshooting:

[ ] DAPR CLI installed (dapr --version)
[ ] DAPR runtime initialized (dapr init)
[ ] Docker running (for local mode)
[ ] Application started with dapr run
[ ] Components in ./components/ directory
[ ] Component names match code references
[ ] Backend services running (Redis, etc.)
[ ] Correct ports configured
[ ] No firewall blocking localhost
[ ] Secrets configured if needed

Log Analysis

Key Log Patterns

# Successful startup
"dapr initialized. Status: Running"

# Component loaded
"component [statestore] loaded"

# Sidecar ready
"dapr sidecar is ready"

# Connection established
"connected to placement service"

# Errors to watch for
"error initializing component"
"failed to connect"
"connection refused"
"unauthorized"
"not found"

Enable Debug Logging

# Local development
dapr run --log-level debug --app-id myapp -- python main.py

# Kubernetes
kubectl set env deployment/myapp DAPR_LOG_LEVEL=debug

Integration with Other Skills

This troubleshooter integrates with:

• config-validator - Validates component YAML syntax
• dapr-debugger agent - Deep debugging assistance
• azure-deployer agent - Azure-specific troubleshooting