Troubleshooting

21. Troubleshooting#

21.1. Common Errors#

403 Forbidden

Cause: The API token lacks the required permissions for the endpoint being accessed.

Fix: Verify the token has the necessary read permissions. See Cloudflare API Permissions Guide for the minimum and recommended permission sets.

No Matching Zones Found

Cause: The --zones filter excluded all zones, or the token cannot enumerate zones in the account.

Fix:

  • Remove --zones to assess all visible zones

  • Verify the token has Zone → Read permission

  • Check that zone names match exactly (case-insensitive)

Unknown Check Categories

Cause: The --checks flag included category names that FlareInspect does not recognize.

Fix: Use only supported categories. Run flareinspect help assess for the full list of 21 categories.

Unknown Compliance Framework

Cause: The --compliance flag or API request used a framework name outside the supported set.

Fix: Use one of: cis, soc2, pci, nist.

Fewer Zones Than Expected

Cause: The token may be scoped to a single Cloudflare account or organization. If your token can only enumerate one zone, the assessment will only cover that zone.

Fix: Verify the token scope and which Cloudflare account it can enumerate.

Assessment Failed

Cause: An API error occurred during assessment. Check the error message for details.

Fix:

  • Run with --debug for verbose API logging

  • Check logs/error.log for stack traces

  • Verify network connectivity to api.cloudflare.com

21.2. Debug Mode#

Enable verbose logging:

flareinspect assess --token $TOKEN --debug

This sets CLOUDFLARE_DEBUG=true and logs every API request and response.

21.3. Logs#

FlareInspect writes logs to:

File

Contents

logs/flareinspect.log

All log levels (rotated at 5 MB, 5 files)

logs/error.log

Error-level logs only

Set LOG_LEVEL=debug for maximum verbosity.