dapr-troubleshooter

name	dapr-troubleshooter
description	Proactively detect and diagnose DAPR runtime issues based on error patterns, log analysis, and common misconfigurations. Provides immediate solutions for service invocation failures, state management issues, pub/sub problems, and deployment errors. Use when encountering DAPR errors or unexpected behavior.
allowed-tools	Read, Grep, Glob, Bash

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