Error Handling

Error Handling

gqlcli surfaces GraphQL errors in a compact, text-friendly way. For non‑JSON formats (such as toon, table, and llm), errors are rendered as plain text; for JSON formats they appear under an errors field alongside any data.

A typical error looks like:

Error: Cannot query field "unknown" on type "Query".
Path: unknown
Code: GRAPHQL_VALIDATION_FAILED

When a query fails, the CLI also prints the offending query with line numbers to make it easier to see where the problem occurred.

Schema Hints (Inline and HTTP Modes)

Both inline and HTTP modes can attach a schemaHint extension to validation errors when the problem mentions a known type. The hint contains a compact SDL description of the relevant type so you can see what fields/arguments actually exist.

Inline Mode

When using Library-Inline-Mode with WithSchemaHints(), validation errors include the SDL definition of the relevant type:

Error: Cannot query field "titl" on type "Book".
Schema hint:
type Book {
  id: ID!
  title: String!
  author: Author!
}

HTTP Mode

When talking to a remote GraphQL server over HTTP, gqlcli introspects the schema and enriches many validation errors with the same schemaHint extension, when the type name can be inferred from the error message.

The exact wording of the error (and presence of a code extension) depends on the upstream server, but when a schemaHint is available it is printed after the error message, similar to inline mode.

Schema hints help both humans and AI agents self‑correct queries without a separate describe call.

Exit Behavior for GraphQL Errors

By default, gqlcli prints GraphQL errors in the selected output format. For scripts and CI, add --fail-on-graphql-errors to exit non-zero whenever a response contains an errors array, even if the HTTP status is 200:

gqlcli query --query-file ./check.graphql --fail-on-graphql-errors
gqlcli batch --file checks.ndjson --fail-on-graphql-errors

Transport-level failures such as connection errors, timeouts, and non-success HTTP responses still return errors. Use --retry, --retry-delay, and --timeout to make automation more resilient.

Response Metadata for Debugging

When diagnosing auth, rate limits, or upstream routing, opt into response metadata:

gqlcli query '{ viewer { id } }' --include-headers
gqlcli query '{ viewer { id } }' --dump-headers headers.txt
gqlcli query '{ viewer { id } }' --metadata status-code --metadata header:X-Request-Id

Metadata is not included by default, so --format json remains machine-parseable unless you request metadata output explicitly.