Troubleshooting

ClawQL is designed around spec-driven discovery and a lean execution path. Most confusion comes from spec selection or expectations about retrieval quality on huge APIs.

GraphQL vs REST

In-process GraphQL uses @omnigraph/openapi (same family as GraphQL Mesh OpenAPI). Some vendor specs hit translation edge cases.

Behavior: When GraphQL resolution fails, execute falls back to REST using the same OpenAPI operation map. search always uses the full OpenAPI-derived index.

Multi-spec mode: execute uses REST for merged corpora; GraphQL applies to single-spec paths where the schema builds cleanly.

Search behavior

Search is intentionally lightweight keyword scoring over operation metadata (MVP). On very large specs you may see noisy rankings or misses; future work may swap in stronger retrieval.

Large specs

ClawQL normalizes specs (refs, nullable patterns, shorthand items, empty servers) so large documents load reliably. The design goal is keep the full spec—efficiency comes from search + selective execute, not from deleting operations.

If startup or pregenerate steps OOM or fail, see maintainer notes in providers/README.md and optional CLAWQL_INTROSPECTION_PATH.

Contributing upstream

To improve OpenAPI→GraphQL translation for everyone, see docs/OPENAPI_TO_GRAPHQL_UPSTREAM.md and CONTRIBUTING.md.