Error Messages
Comprehensive guide to understanding and resolving CDK Insights error messages. Find quick solutions to common issues and learn how to prevent them in the future.
Quick Error Resolution
Installation & Setup
Issues with CDK Insights installation and initial setup
Command not found: cdk-insights
Cause:
CDK Insights is not installed or not in PATH
Solution:
- Install globally: npm install -g cdk-insights
- Or use npx: npx cdk-insights scan
- Verify installation: npm list -g cdk-insights
Prevention: Use npx for one-time usage or install globally for regular use
Cannot find module 'aws-cdk-lib'
Cause:
AWS CDK dependencies are missing
Solution:
- Install CDK: npm install aws-cdk-lib
- Ensure you are in a CDK project directory
- Run: npm install to install all dependencies
Prevention: Always run from within a properly configured CDK project
No CDK app found in current directory
Cause:
Not running from a CDK project root or missing cdk.json
Solution:
- Navigate to your CDK project root directory
- Ensure cdk.json exists in the current directory
- Verify CDK app structure is correct
Prevention: Always run CDK Insights from your CDK project root
AWS Credentials & Permissions
Issues with AWS authentication and permissions
Unable to locate credentials
Cause:
AWS credentials not configured or expired
Solution:
- Configure AWS CLI: aws configure
- Set environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
- Use IAM roles if running on EC2
- Check credential expiration for temporary credentials
Prevention: Use IAM roles when possible and monitor credential expiration
Access Denied: User is not authorized
Cause:
Insufficient AWS permissions for analysis
Solution:
- Ensure user has required IAM permissions
- Check IAM policies for CDK-related services
- Use AWS managed policies or create custom policies
- Verify region permissions
Prevention: Grant minimal required permissions for CDK analysis
Invalid region specified
Cause:
AWS region is not configured or invalid
Solution:
- Set AWS_DEFAULT_REGION environment variable
- Configure region in AWS CLI: aws configure set region us-east-1
- Specify region in CDK app configuration
- Verify region is supported for your resources
Prevention: Always specify a valid AWS region in your configuration
Analysis & Processing
Issues during the analysis process
No stacks found to analyze
Cause:
CDK app has no stacks or stacks failed to synthesize
Solution:
- Verify stacks are defined in your CDK app
- Run: cdk synth to test synthesis
- Check for CDK synthesis errors
- Ensure stacks are properly exported
Prevention: Always test CDK synthesis before running analysis
Analysis timeout - operation took too long
Cause:
Large CDK app or network issues causing delays
Solution:
- Use --timeout flag to increase timeout
- Limit analysis scope with --services flag
- Enable caching to speed up subsequent runs
- Check network connectivity
Prevention: Use service filtering and caching for large projects
Failed to parse CloudFormation template
Cause:
Malformed or invalid CloudFormation output
Solution:
- Verify CDK synthesis produces valid CloudFormation
- Check for CDK version compatibility issues
- Review CDK app for syntax errors
- Update CDK dependencies if needed
Prevention: Keep CDK dependencies up to date and test synthesis regularly
Output & Reporting
Issues with output generation and formatting
Failed to write output file
Cause:
Insufficient permissions or disk space
Solution:
- Check file system permissions
- Ensure sufficient disk space
- Verify output directory exists
- Use absolute paths for output files
Prevention: Ensure write permissions and adequate disk space
Invalid output format specified
Cause:
Unsupported or incorrectly specified output format
Solution:
- Use supported formats: table, json, markdown, summary
- Check format parameter spelling
- Update to latest CDK Insights version
- Refer to documentation for format options
Prevention: Use documented output formats and keep tools updated
GitHub integration failed
Cause:
GitHub token issues or repository access problems
Solution:
- Verify GitHub token is valid and not expired
- Check token permissions (issues, repository access)
- Ensure repository name format is correct (owner/repo)
- Test token with GitHub API directly
Prevention: Use fine-grained tokens and monitor token expiration
Debugging Tips
Enable Verbose Logging
Get detailed information about what CDK Insights is doing
npx cdk-insights scan --verboseBenefit: Identify exactly where the process fails
Check CDK Synthesis
Verify your CDK app can synthesize properly
cdk synthBenefit: Ensure CDK app is valid before analysis
Test with Minimal Scope
Run analysis on a single service to isolate issues
npx cdk-insights scan --services S3Benefit: Narrow down the source of problems
Clear Cache
Remove cached data that might be causing issues
npx cdk-insights cache:clearBenefit: Start fresh when cache corruption is suspected
Common Solutions
Analysis takes too long
Too many findings
Memory usage is high
Still Need Help?
Before Contacting Support
- Check this error message guide
- Try the debugging tips above
- Run with --verbose for detailed logs
- Check CDK Insights version compatibility
When Reporting Issues
- Include the complete error message
- Provide CDK Insights version
- Include relevant configuration
- Describe steps to reproduce
Issue Resolved?
If you've resolved your issue, continue exploring CDK Insights features and configuration options.