Skip to main content
ClawQL

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.

Dashboard operations checklist (Helm / Kubernetes)

Use this when http://clawql.localhost is failing, dashboard sync appears stuck, or Vault updates are not reflected in clawql-mcp-http.

  1. Check dashboard HTTP health:
curl -sS http://clawql.localhost/api/k8s/health
  1. Check dashboard workload objects:
kubectl -n clawql get deploy,svc,ingress | rg dashboard
kubectl -n clawql get pods -l app.kubernetes.io/component=dashboard
  1. Verify dashboard container env wiring (Vault + rollout target):
kubectl -n clawql get deploy clawql-mcp-http-dashboard -o yaml | rg "CLAWQL_DASHBOARD_(VAULT|K8S)_" -n
  1. Verify rollout target exists and is healthy:
kubectl -n clawql get deploy clawql-mcp-http
kubectl -n clawql rollout status deploy/clawql-mcp-http --timeout=180s
  1. Verify Vault value directly from Vault pod:
kubectl -n clawql exec clawql-vault-0 -- sh -lc 'VAULT_ADDR=http://127.0.0.1:8200 VAULT_TOKEN="${VAULT_DEV_ROOT_TOKEN_ID:-root}" vault kv get -field=ONYX_BASE_URL secret/provider/env'

If these checks pass but the UI is still stale, restart the dashboard deployment and retry one save:

kubectl -n clawql rollout restart deploy/clawql-mcp-http-dashboard
kubectl -n clawql rollout status deploy/clawql-mcp-http-dashboard --timeout=180s

Contributing upstream

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