Troubleshooting

Common issues and their solutions when using the XnoleX platform.

Scan Stuck in Queue

If a scan remains in queued status for an extended period:

• Check your concurrent scan limit: Demo=1, Monthly=3, Yearly=5
• Check the system-wide concurrent limit of 10 scans
• Existing running scans must complete or be stopped before queued scans begin
• Scans stuck for more than 2 hours are automatically marked as failed

Tier Concurrent Limits:
  Demo (Free):  1 concurrent scan
  Monthly Pro:  3 concurrent scans
  Yearly Pro:   5 concurrent scans
  System-wide: 10 concurrent scans

Scan Failed

A scan may fail for several reasons:

• The target domain is not a valid, resolvable domain
• The engine name is not one of: full, subdomain, nuclei
• Required scan tools are not installed or accessible on the server
• The target domain does not resolve to any IP addresses

Target Validation Failed

Target domains must pass validation before being accepted:

• Must be a valid Fully Qualified Domain Name (FQDN)
• Cannot be localhost or internal/private IPs
• Cannot target xnolex.com or its subdomains
• Must not contain protocol prefixes (e.g., https://)

No Findings Returned

A scan returning zero findings does not necessarily indicate an error:

• Not all targets have discoverable vulnerabilities
• Use the full engine for the most comprehensive scan
• Ensure nuclei templates are installed and up to date
• The subdomain engine focuses on discovery, not vulnerability detection

Authentication Errors

Common authentication issues:

• Token expired: Access tokens expire after 15 minutes. Use your refresh token to obtain a new pair.
• Invalid format: Ensure the Authorization header uses Bearer YOUR_TOKEN format.
• Max sessions exceeded: You can have up to 5 concurrent refresh token sessions. The oldest is revoked on new login.

# Correct Authorization header format
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

# Correct API key header format
X-API-Key: xnk_your_api_key_here

API Rate Limit Exceeded

When you receive a 429 Too Many Requests response:

• Check your tier's RPM limit: Demo=10, Monthly=60, Yearly=120, Admin=200
• Wait before retrying — rate limits reset on a per-minute sliding window
• Implement exponential backoff in automated integrations
• Consider upgrading your tier for higher limits

WebSocket Connection Issues

If the WebSocket connection fails to establish or immediately closes:

• Ensure a valid JWT is provided in the token query parameter
• Verify the scan exists and you are the owner
• Check the WebSocket URL format: ws://host/api/v1/ws/scans/{scan_id}?token={jwt}
• Expired tokens will be rejected on connection

Billing & Subscription Issues

Common billing-related issues:

• Check your current subscription status via GET /api/v1/subscriptions/current
• Demo tier has limited scans (5 total) — upgrade via the Settings page for more
• Scan limits are enforced per subscription and reset with billing cycle for monthly/yearly plans
• If you recently upgraded, allow a few minutes for Stripe webhook processing
• Cancelled subscriptions remain active until the end of the billing period