Debugging

The plugin provides deep, request-level visibility into query execution: a @debug directive that profiles queries through Brightspot's Dari profiler, structured error extensions, and schema-load diagnostics. Combined with the GraphQL Explorer, these tools cover the everyday debugging workflows for both development and production.

The @debug directive

Attach @debug to an operation (or a specific field/fragment) to profile its execution:

1
query GetArticles @debug {
2
  Query {
3
    Records(from: {type: Article}, limit: 10) {
4
      items {
5
        ... on Article { headline }
6
      }
7
    }
8
  }
9
}

The response gains a profilerResult entry in its extensions containing the Dari profiler's event tree for the request: which data fetchers ran, in what order, and how long each took—including the database queries the GCA executed on your behalf. This is the fastest way to answer "why is this query slow": look for the fetches with large durations or unexpectedly high counts (the classic N+1 reference-resolution pattern shows up immediately).

@debug takes an optional if: Boolean argument and can be scoped to fragments or individual fields when you want to profile just part of a large query. Debug output is gated—requests must be authorized for debugging (e.g. authenticated via Brightspot's debug mechanisms or the X-Debug header with appropriate credentials), so casual API consumers can't extract profiling data.

Error extensions

Errors follow the GraphQL spec's errors array, with machine-readable detail in extensions:

• Timeouts include the configured timeout and elapsed time.
• Complexity rejections include the computed complexity and remaining budget.
• Validation errors carry a classification (e.g. ValidationError) plus source locations.
• Dry runs add a dryRuns extension listing rolled-back operations.

During development on GCA endpoints, verboseClientErrors() surfaces underlying exception detail in errors; keep it off in production and correlate with server logs instead.

Common issues

Slow queries

1. Profile with @debug and find the expensive fetches.
2. Reference traversals are database fetches—trim selection sets, or restructure to use embedded data where appropriate.
3. Check pageInfo-only optimizations (selecting just count avoids fetching items).
4. Bound the blast radius with timeouts and complexity budgets.

Null results where you expect data

• The field may be excluded by a fieldFilter, or the reference may be blocked by the referenceTypeFilter—a RecordRef with only _id/_type populated is the giveaway.
• Visibility: archived or invisible records resolve to null through references unless options: {resolveInvisible: true}.
• Merged field/getter behavior: a getter may compute null where raw state has a value—test with @bsp_raw.

Permission and access errors

• Confirm the API key/client headers are present and valid (see Security).
• On site-scoped GCA endpoints, the content must be accessible from the supplied site.
• Mutations additionally require the type to be mutable and the action to be configured.

Schema problems

If an endpoint fails to serve, the schema may have failed to load—schema load errors are captured with full details for inspection, and the endpoint reports the failure rather than serving a partial schema. Common causes are type-name conflicts (pin names with naming functions) and invalid settings (strictMode() surfaces these at build time instead of silently omitting them). For slow schema loads, enable profileSchemaLoad() temporarily.

For schema changed unexpectedly investigations, diff the recorded schema versions—see schema versioning.

Debugging workflow tips

• Develop queries in the Explorer: schema docs, autocompletion, and error squiggles catch most issues before any client code exists.
• Reproduce API behavior exactly by matching headers (API key, site header, debug header)—the Explorer sends them for you.
• Test failure paths deliberately: invalid IDs, missing required arguments, over-limit queries. Confirm your clients handle the structured errors above.

Next steps

• Security — timeouts, depth, and complexity configuration
• Analytics — endpoint-level usage monitoring