Common Issues
Troubleshoot common CDK Insights issues. Find solutions for installation problems, analysis failures, and configuration issues.
Quick Diagnostic
Before diving into specific issues, run this quick diagnostic to identify common problems:
# Check prerequisites
node --version && npm --version && aws --version && cdk --version
# Test CDK Insights
npx cdk-insights --help
# Verify CDK app
cdk synthIf any of these commands fail, refer to the specific issue categories below for detailed solutions.
Issues by Category
Installation Issues
❌ cdk-insights: command not found
Cause: CDK Insights is not installed or not in PATH
Solution:
- →Use npx to run without installation: npx cdk-insights scan
- →Install globally: npm install -g cdk-insights
- →Install as dev dependency: npm install --save-dev cdk-insights
❌ Permission denied errors
Cause: Insufficient permissions for global installation
Solution:
- →Use npx instead of global installation
- →Fix npm permissions: npm config set prefix ~/.npm-global
- →Use sudo for global install (not recommended)
❌ Node.js version compatibility
Cause: Using unsupported Node.js version
Solution:
- →Update to Node.js 22 or higher
- →Use nvm to manage Node.js versions
- →Check compatibility: node --version
Analysis Issues
❌ No stacks found to analyze
Cause: CDK app not synthesized or no stacks defined
Solution:
- →Run cdk synth first to generate CloudFormation templates
- →Check that your CDK app has stacks defined
- →Verify you are in the correct directory
- →Use --synth flag: npx cdk-insights scan --synth
❌ CDK synthesis failed
Cause: CDK cannot synthesize templates (missing dependencies or configuration)
Solution:
- →Ensure all CDK dependencies are installed: npm install
- →Verify CDK app is valid: cdk synth
- →Check for TypeScript compilation errors
- →Ensure AWS credentials are configured
❌ AWS credentials not configured
Cause: AWS credentials not set up or expired
Solution:
- →Run aws configure to set up credentials
- →Check environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
- →Use IAM roles if running on EC2
❌ Analysis takes too long
Cause: Large CDK app or network issues
Solution:
- →Limit analysis scope: --services S3,IAM
- →Use caching to speed up subsequent runs
- →Check network connectivity to AWS
Configuration Issues
❌ Configuration not being applied
Cause: Invalid JSON or wrong file location
Solution:
- →Validate JSON syntax in .cdk-insights.json
- →Ensure file is in CDK project root directory
- →Check file permissions and accessibility
❌ Unknown configuration option
Cause: Using unsupported configuration option
Solution:
- →Check documentation for supported options
- →Validate configuration against schema
- →Remove unsupported options
❌ Output format not working
Cause: Invalid format specified or missing dependencies
Solution:
- →Use supported formats: table, json, markdown, summary, sarif, github-actions
- →Check that --output flag is correctly specified
- →Verify file permissions for output files
Systematic Troubleshooting
Check Prerequisites
Verify all required tools are installed and configured
node --version # Should be 18+npm --versionaws --versioncdk --versionVerify CDK App
Ensure your CDK application is properly set up
cdk synth # Should complete without errorsls -la cdk.out # Should contain CloudFormation templatesTest CDK Insights
Run CDK Insights with verbose output
npx cdk-insights scan --help # Check available optionsnpx cdk-insights scan --output json # Test with JSON outputCheck Logs
Review error messages and logs for specific issues
npx cdk-insights scan 2>&1 | tee analysis.logcat analysis.log # Review for specific error messagesPerformance Optimization
Use Caching
Enable caching to speed up subsequent analysis runs
Implementation: CDK Insights automatically caches synthesis results
Limit Scope
Analyze only specific services or stacks when possible
Implementation: Use --services or --stacks flags to limit analysis scope
Parallel Analysis
Use --all flag to analyze multiple stacks in parallel
Implementation: npx cdk-insights scan --all
Skip Synthesis
Skip CDK synthesis if templates are already generated
Implementation: Ensure cdk.out exists before running analysis
Still Need Help?
📚 Additional Resources
💬 Contact Support
- Email Support
Include error logs and system information for faster resolution
Resolved Your Issue?
Great! Now you can focus on analyzing your CDK infrastructure and improving your deployment practices.