Skip to main content
When an NQL query fails, the platform returns a structured error response with details about what went wrong. This section helps you diagnose and resolve common errors.

​
Understanding error responses

NQL errors return a JSON response with the following structure: 
{
  "type": "https://www.narrative.io/knowledge-base/...",
  "title": "Error Title",
  "status": 422,
  "detail": "Detailed explanation of what went wrong",
  "instance": "/nql/run",
  "logId": "unique-error-identifier"
}
FieldDescription
typeURL identifying the error type
titleBrief error summary
statusHTTP status code (typically 422 for validation errors)
detailDetailed explanation of the problem
instanceThe API endpoint that produced the error
logIdUnique identifier for support requests
When contacting support about an error, include the logId value to help quickly identify your specific issue.

​
Common errors

Cross-Data Plane Queries

Resolve errors when queries reference datasets in different data planes

Unsupported Type Errors

Fix type mismatches and unsupported operations in your queries

​
General troubleshooting steps

  1. Read the error detail — The detail field usually explains exactly what’s wrong
  2. Check the instance — Identifies whether the error occurred during parsing (/nql/parse) or execution (/nql/run)
  3. Review your query — Look for the specific element mentioned in the error
  4. Consult the reference — Check NQL syntax and data types for supported operations