Skip to main content
Skip to main content

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 synth

If 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 18 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
  • →Check that --format flag is correctly specified
  • →Verify file permissions for output files

Systematic Troubleshooting

1

Check Prerequisites

Verify all required tools are installed and configured

node --version # Should be 18+
npm --version
aws --version
cdk --version
2

Verify CDK App

Ensure your CDK application is properly set up

cdk synth # Should complete without errors
ls -la cdk.out # Should contain CloudFormation templates
3

Test CDK Insights

Run CDK Insights with verbose output

npx cdk-insights scan --help # Check available options
npx cdk-insights scan --format json # Test with JSON output
4

Check Logs

Review error messages and logs for specific issues

npx cdk-insights scan 2>&1 | tee analysis.log
cat analysis.log # Review for specific error messages

Performance 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?

💬 Contact Support

Resolved Your Issue?

Great! Now you can focus on analyzing your CDK infrastructure and improving your deployment practices.

Quick Start GuideLearn About Features