Troubleshooting
Spec Upload Issues
”The specification file format is invalid”
The uploaded file is not valid JSON or YAML.
Fix: Validate your file with a linter (such as jq . openapi.json for JSON or a YAML validator for YAML files) and correct any syntax errors.
”The specification version is not supported”
See supported formats. Other formats, such as Postman collections and HAR files, are not accepted.
Fix: Ensure your spec includes the correct version field ("swagger": "2.0" or "openapi": "3.0.x" / "openapi": "3.1.x").
”The specification contains an invalid reference” or “Component ’…’ not found in specification”
Your spec contains $ref references that can’t be resolved. References to other local files are not loaded.
Fix: Bundle your spec into a single file with all references inlined. Tools such as swagger-cli bundle or redocly bundle can do this automatically.
”The specification file does not contain any API paths”
The parser found no scannable endpoints.
Fix: Verify that your spec has entries under the paths object with at least one HTTP method defined for each path.
”The specification file does not contain any server definitions”
The file must contain at least one server address in its servers field. Each server address must be a valid URL, such as https://api.example.com, not /.
Server Address Not Verified
You can only scan server addresses that are verified assets in your Detectify account. If a server address in your file isn’t verified, you’re asked to add and verify it before you can continue. See Asset Verification.
GraphQL Schema Issues
- “The GraphQL schema file format is invalid”: the file must be a valid GraphQL SDL file or a GraphQL introspection JSON response.
- “The GraphQL schema does not contain any query or mutation definitions”: only queries and mutations can be tested, so the schema needs at least one of them.
Authentication Issues
Test Operation Shows “Failed operation”
When Test operation shows Failed operation, open Investigate for details. If the scanner can’t authenticate with your API:
- API Key: Verify where the key is sent (Header, Query or Cookie), and that its name and value are correct. Check whether the key has expired.
- OAuth: Ensure the Access token URL, Client ID, Client secret and scopes are correct. For OAuth / Authorization Code, check that the Redirect URI is on the allowlist at your identity provider.
Token Expiration During Scan
If your API uses short-lived tokens entered as an API key, the scanner loses authentication when the token expires, because it isn’t renewed.
Fix: Configure OAuth / Client Credentials or OAuth / Authorization Code so the scanner can get new tokens automatically. Alternatively, use a long-lived API key for scanning purposes.
Scan Performance Issues
Scan Takes Too Long
Long scan times are usually caused by:
- Large number of endpoints. APIs with hundreds of endpoints naturally take longer. Consider narrowing the scan scope if you want faster results.
- Strict rate limiting. Very low request rate limits extend scan duration significantly.
Scan Produces No Findings
A scan with zero findings does not necessarily mean your API is secure. Possible reasons include:
- Authentication failure. Without working authentication, the scanner can only look for shallow security issues and doesn’t get full coverage.
- Incomplete spec. Endpoints not defined in the spec are not tested.
- WAF blocking. If your WAF blocks scanner traffic, payloads never reach the API. API Scanning traffic comes from the same IP addresses as Detectify’s other scanning, with the user agent
Mozilla/5.0 (compatible; Detectify; api-scanning). See Network Setup for allowlisting instructions. - Selected operations are misconfigured. If an operation has been selected as a part of the scope, but missing or invalid parameter values mean no working API calls can be made, which reduces what the scan can find.
Getting Help
If you encounter an issue not covered here, contact Detectify support at support@detectify.com.