Troubleshooting

Solutions for common issues you may encounter when using Doku.

"Permission denied" on deploy

Cause: Your cloud provider credentials are missing, expired, or lack the required IAM permissions.

Fix:

1. Verify your credentials are set: echo $AWS_ACCESS_KEY_ID (or equivalent for GCP/Azure)
2. Check that the IAM user/role has the required permissions — see Cloud Providers
3. If using temporary credentials (STS), make sure they haven't expired
4. Run doku auth whoami to verify your Doku authentication is valid

Deploy stuck in "provisioning"

Cause: Infrastructure creation is taking longer than expected, often due to cloud provider rate limits or resource quotas.

Fix:

1. Run doku deploy --verbose to see detailed provisioning logs
2. Check your cloud provider's console for resource limits (ECS task limits, VPC quotas, etc.)
3. If the deployment is truly stuck, cancel it with Ctrl+C and retry

Canary failed, deployment rolled back

Cause: The new version exceeded error rate or latency thresholds during canary rollout.

Fix:

1. Check the deployment logs: doku logs --env staging --since 30m --level error
2. Review the deployment output for the specific metric that triggered rollback
3. Fix the issue in your application code
4. Re-deploy with doku deploy

Cloud credentials not found

Doku looks for cloud credentials in this order:

1. Environment variables (AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.)
2. Cloud CLI configuration (~/.aws/credentials, gcloud auth, az login)
3. Instance metadata (when running on a cloud VM with an attached role)

Make sure at least one of these is configured. See provider-specific setup in Cloud Providers.

Health check failing

Cause: The health check endpoint in your doku.yaml is not responding with a 200 status.

Fix:

1. Verify your application has a health check endpoint (e.g., /health or /api/health)
2. Make sure it returns HTTP 200 when the application is ready to serve traffic
3. Check that the port in doku.yaml matches the port your app listens on

// Example health check endpoint (Express)
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' });
});

Debug Mode

For detailed debugging output, use the --verbose flag:

doku deploy --verbose

This prints infrastructure plan details, container build logs, health check results, and canary metrics at each rollout step.

Getting Help

• GitHub Issues — Report bugs and request features on the Doku GitHub repository
• Discord — Join the Doku community for real-time help
• Email — Reach the team at support@doku.io