Skip to content

Troubleshooting

Solutions to common issues with IAM Policy Validator.

Installation Issues

Command Not Found

If iam-validator is not found after installation:

# Check if installed
pip show iam-policy-validator

# Ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Or use Python module directly
python -m iam_validator.core.cli validate --path policy.json

Permission Denied

# Use --user flag
pip install --user iam-policy-validator

# Or use virtual environment
python -m venv .venv
source .venv/bin/activate
pip install iam-policy-validator

Validation Issues

No Policies Found

# Check file extension
ls -la *.json *.yaml

# Use verbose mode
iam-validator validate --path ./policies/ --verbose

Invalid JSON

If you get JSON parsing errors:

  1. Validate JSON syntax with jq:
jq . policy.json

  1. Check for trailing commas (not allowed in JSON)

  2. Ensure proper encoding (UTF-8)

Action Not Found

If valid actions are reported as invalid:

# Update AWS service cache
iam-validator cache clear
iam-validator download-services

Performance Issues

Slow Validation

For large policy sets:

# Pre-download service definitions
iam-validator download-services

# Use JSON output (faster than enhanced)
iam-validator validate --path ./policies/ --format json

High Memory Usage

For very large directories:

# Validate in batches
find ./policies -name "*.json" | xargs -n 10 iam-validator validate --path

GitHub Actions Issues

Rate Limiting

GitHub API rate limits can affect PR comments:

- uses: boogy/iam-policy-validator@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    # Token has higher rate limits than unauthenticated

Comments Not Appearing

Check workflow permissions:

permissions:
  contents: read
  pull-requests: write

Getting Help