Skip to content

Troubleshooting Best Practices

Systematic Diagnosis

  1. Review Problem Codes: Examine specific problem codes reported for each failed scan
  2. Check Event Logs: Follow diagnostic links to detailed event logs for context
  3. Verify Configuration: Confirm scan configuration matches target environment requirements
  4. Test Connectivity: Validate network connectivity and service availability
  5. Review Credentials: Ensure authentication credentials remain valid and have sufficient permissions

Common Resolution Paths

Problem Code Reference

Use the code and message together to choose what to investigate. These are the severities defined for each code; the diagnostics card shows the severity reported for the scan.

Code UI Title Severity What to Check
PL_FAILURE Private Location Failure Error Private Location connectivity
AUTH_FAILURE Authentication Failure Error Credentials and authentication configuration, then authentication logs
CONFIGURATION_IMPROVEMENT Configuration Improvement Info The configuration change suggested in the problem message
SCHEMA_IMPROVEMENT Schema Improvement Info The schema issue described in the problem message
HIGH_NUMBER_OF_ERROR_ENDPOINTS High Number of Error Endpoints Warning Endpoint responses and target application logs
UNREACHABLE_ASSET Unreachable Asset Error Target availability, DNS, routing, and firewall rules
TIMEOUT Timeout Error Scan logs, target response times, and configured duration
INTEGRATION_ERROR Integration Error Error Integration logs and configuration
CAPTCHA_HIT Captcha Hit Warning CAPTCHA handling and allowlisting
BLOCKED_BY_WAF Blocked by WAF Warning WAF allowlisting
RATE_LIMIT_EXCEEDED Rate Limit Exceeded Warning Request rate configuration
NO_SCHEMA_FOUND No schema found Info Linked API schemas
NO_AUTHENTICATION_CONFIGURED No authentication configured Info Authentication configuration; the scan tests only the public user
UNEXPECTED_ERROR Unexpected error Error Related events; contact support with diagnostic details if it persists

Connection Failures

  • Verify target service availability using external monitoring tools
  • Confirm DNS resolution and network routing
  • Check private location health and connectivity
  • Review firewall and security group configurations

Authentication Failures

  • Validate credentials against target environment
  • Confirm authentication method compatibility
  • Review token expiration and refresh mechanisms
  • Test authentication flow manually to identify issues

Configuration Issues

  • Compare scan configuration against target API requirements
  • Validate schema files for syntax and structure
  • Review rate limiting and concurrency settings
  • Confirm scope and URL pattern configurations

Escalation

If problems persist after following diagnostic guidance:

  1. Export detailed diagnostic information via API
  2. Capture relevant event logs and error messages
  3. Document configuration settings and recent changes
  4. Contact Escape support with collected diagnostic data

Monitoring Recommendations

  • Enable API Access: Configure monitoring systems to poll the problems API endpoint
  • Set Up Alerts: Create notifications for critical problem codes
  • Track Trends: Monitor problem code frequency over time to identify systemic issues
  • Review Regularly: Establish periodic reviews of scan quality metrics