# 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](<https://docs.escape.tech/documentation/platform/private-location/connectivity/index.md>) |
| `AUTH_FAILURE` | Authentication Failure | Error | [Credentials and authentication configuration](<https://docs.escape.tech/documentation/platform/authentication/index.md>), 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](<https://docs.escape.tech/documentation/platform/firewall/index.md>) |
| `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](<https://docs.escape.tech/documentation/platform/authentication/captcha-authentication/index.md>) and [allowlisting](<https://docs.escape.tech/documentation/platform/firewall/index.md>) |
| `BLOCKED_BY_WAF` | Blocked by WAF | Warning | [WAF allowlisting](<https://docs.escape.tech/documentation/platform/firewall/index.md>) |
| `RATE_LIMIT_EXCEEDED` | Rate Limit Exceeded | Warning | [Request rate configuration](<https://docs.escape.tech/documentation/dast/api-testing/rate-limiting/index.md>) |
| `NO_SCHEMA_FOUND` | No schema found | Info | [Linked API schemas](<https://docs.escape.tech/documentation/platform/scan-quality/include-extra-data/index.md>) |
| `NO_AUTHENTICATION_CONFIGURED` | No authentication configured | Info | [Authentication configuration](<https://docs.escape.tech/documentation/platform/authentication/index.md>); the scan tests only the public user |
| `UNEXPECTED_ERROR` | Unexpected error | Error | Related events; contact support with diagnostic details if it persists |
| `BLOCKED_BY_CORS` | Blocked by CORS | Warning | The API's CORS headers, and custom or authentication headers that the API does not allow |

### 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