Troubleshooting

This page covers common issues encountered when working with the Lumar GraphQL API and how to diagnose them.

401 Unauthorized

Symptom: Every request returns HTTP 401 or an UNAUTHENTICATED error.

Diagnosis: Verify your authentication is working by running a simple me query:

Operation: query CheckMyPermissions { me { id username accounts(first: 5) { nodes { id name } } } }Response Example: { "data": { "me": { "id": "TjAwNFVzZXI4NjE", "username": "your.username@example.com", "accounts": { "nodes": [ { "id": "TjAwN0FjY291bnQ3MTU", "name": "Your Account Name" } ] } } } }

CheckMyPermissionsTry in Explorer

GraphQL

query CheckMyPermissions {
  me {
    id
    username
    accounts(first: 5) {
      nodes {
        id
        name
      }
    }
  }
}

Common causes:

• The x-auth-token header is missing or misspelt.
• The session token has expired. Re-authenticate using createSessionUsingUserKey.
• The user key or service account key has been revoked.

Empty results

Symptom: A query returns an empty nodes array when you expect data.

Common causes:

• The crawl has not finished yet. Check the crawl status:

Operation: query VerifyCrawlStatus($crawlId: ObjectID!) { getCrawl(id: $crawlId) { id status createdAt finishedAt crawlUrlsTotal crawlLevels } }Variables: { "crawlId": "TjAwNUNyYXdsMTU4MzI0NQ" }Response Example: { "data": { "getCrawl": { "id": "TjAwNUNyYXdsMTU4MzI0NQ", "status": "Finished", "createdAt": "2025-01-15T10:00:00.000Z", "finishedAt": "2025-01-15T10:30:00.000Z", "crawlUrlsTotal": 2186, "crawlLevels": 5 } } }

VerifyCrawlStatusTry in Explorer

GraphQL

query VerifyCrawlStatus($crawlId: ObjectID!) {
  getCrawl(id: $crawlId) {
    id
    status
    createdAt
    finishedAt
    crawlUrlsTotal
    crawlLevels
  }
}

• You are querying a report template that has no matching URLs for this crawl.
• A filter is too restrictive. Remove filters temporarily to confirm data exists, then add them back incrementally.
• You are querying the wrong account or project. Verify the ID using the me query above.

Rate limit errors (429)

Symptom: Requests fail with HTTP 429 Too Many Requests.

Solution:

• Reduce request frequency to stay under the 6000 requests / 5-minute limit.
• Implement exponential backoff (see Error Handling).
• Combine multiple small queries into a single larger query where possible.

Crawl stuck in Queued or Crawling status

Symptom: A crawl never reaches Finished status.

Common causes:

• The site is very large and the crawl is still in progress. Use the crawl status query above to check crawlUrlsTotal for progress.
• The crawl hit an error and moved to an error state. Check the status field -- if it shows Paused or an unexpected state, the crawl may need attention.
• Rate limiting on the target site is slowing the crawl. Check your project's crawl rate settings.

Missing webhook notifications

Symptom: Webhooks are configured but no notifications are received.

Checklist:

1. Verify the webhook exists on the test suite (query the webhooks or slackWebhooks connection on the test suite).
2. Confirm the alertTypes include the relevant alert level (e.g., Fail).
3. Check that the webhook URL is accessible from the internet and returns a 2xx response.
4. For Slack webhooks, verify the incoming webhook URL is still active in your Slack workspace settings.
5. Ensure a build has actually completed -- webhooks fire only when a build finishes.

Query validation errors

Symptom: The API returns a 400 status with syntax or validation errors.

Common causes:

• A required variable is missing. Check the query signature for required (!) parameters.
• An enum value is incorrect (e.g., using "Finished" as a string instead of the enum Finished).
• The query references a field that does not exist on the type. Use the schema explorer to verify field names.

Timeout or slow responses

Symptom: Requests take a very long time or time out.

Solutions:

• Reduce the first parameter to fetch fewer records per page.
• Remove deeply nested relationship fields that trigger additional data loading.
• Avoid requesting totalCount on very large connections if you do not need it.
• Use report downloads for bulk data export instead of paginating through the API (see Generate Report Downloads).