Setting the file. One moment.
Subchapter 8.7
references/troubleshooting.mdMarkdown8 KBView on GitHub
Error: No supergraph schema provided
Error: No supergraph schema found. Provide --supergraph or set APOLLO_GRAPH_REF.Fix: Provide a supergraph schema:
# Local file
router --supergraph ./supergraph.graphql
# Or GraphOS managed
export APOLLO_KEY=service:my-graph:key
export APOLLO_GRAPH_REF=my-graph@production
routerError: Invalid configuration
Error: configuration error: unknown field `cors`Fix: Check YAML syntax and field names:
# Validate config
router config validate router.yamlError: Address already in use (os error 48)Fix: Use a different port or stop the existing process:
# Check what's using the port
lsof -i :4000
# Use different port
router --supergraph ./supergraph.graphql --listen 127.0.0.1:4001Error: Connection refused
Error: error sending request for url (http://localhost:4001/graphql): error trying to connectChecklist:
curl -X POST http://localhost:4001/graphql -H "Content-Type: application/json" -d '{"query":"{ __typename }"}'Override subgraph URL for local development:
# router.yaml
override_subgraph_url:
products: http://host.docker.internal:4001/graphqlError: Timeout
Error: operation timed outIncrease timeout:
traffic_shaping:
subgraphs:
slow-service:
timeout: 60sError: Failed to fetch schema from Uplink
Error: failed to fetch schema: Uplink request failedChecklist:
APOLLO_KEY is correctAPOLLO_GRAPH_REF format: graph-id@variant# Test connection
curl -H "X-Api-Key: $APOLLO_KEY" \
https://uplink.api.apollographql.com/Error: Introspection disabled
{
"errors": [{ "message": "Introspection has been disabled" }]
}Fix: Enable introspection (development only):
supergraph:
introspection: trueOr use --dev mode:
router --dev --supergraph ./supergraph.graphqlSandbox requires introspection. Enable both:
supergraph:
introspection: true
sandbox:
enabled: trueOr use --dev mode which enables both.
Error: Browser blocked by CORS policy
Access to fetch has been blocked by CORS policy: No 'Access-Control-Allow-Origin' headerFix: Configure CORS using the correct schema for your Router version:
v1 (flat schema):
cors:
origins:
- http://localhost:3000
- https://studio.apollographql.com
allow_headers:
- Content-Type
- Authorizationv2 (policies schema):
cors:
max_age: 24h
policies:
- origins:
- http://localhost:3000
- https://studio.apollographql.com
allow_headers:
- Content-Type
- AuthorizationFor development (not production):
# v1
cors:
origins:
- "*"
# v2
cors:
allow_any_origin: trueCORS config ignored after upgrading to v2:
If you upgraded from v1 to v2 and your CORS settings stopped working, you’re
likely using the v1 flat schema (cors.origins). v2 requires the policies
array format (cors.policies). See the divergence map
for the full diff. You can auto-migrate with: router config upgrade router.yaml
If you migrated from v1 to v2 and kept the singular issuer field instead
of the plural issuers array, the config uses a v1-only field. Use issuers
for Router v2.
Broken (v1 field in v2 config):
authentication:
router:
jwt:
jwks:
- url: https://auth.example.com/.well-known/jwks.json
issuer: https://auth.example.com/ # WRONG for v2!Fixed (v2 field):
authentication:
router:
jwt:
jwks:
- url: https://auth.example.com/.well-known/jwks.json
issuers: # Correct for v2
- https://auth.example.com/Debug steps:
telemetry:
exporters:
logging:
stdout:
enabled: true
format: jsonCheck subgraph latency: Enable tracing to identify slow subgraphs.
Enable caching:
supergraph:
query_planning:
cache:
in_memory:
limit: 512supergraph:
query_planning:
cache:
in_memory:
limit: 256 # Reduce from defaultCache-Control without no-storeCache-Control: max-age=N (via @cacheControl in Apollo Server, or set directly in other frameworks)Cache-Control: private requires private_id to be configured on the routerapollo.router.cache.redis.errors metricresponse_cache.debug: true and use Apollo Sandbox to inspect cache stateRouter logs composition errors:
Error: Subgraph schema validation failedFix: Validate schema before deploying:
rover subgraph check my-graph@production \
--name products \
--schema ./schema.graphqlError: Cannot resolve entity
{
"errors": [{ "message": "cannot resolve entity of type User" }]
}Checklist:
_entities query@key fields match between subgraphsCheck Router health on the configured health listener (the provided templates use 127.0.0.1:8088/health):
curl http://localhost:8088/healthExpected response:
{"status":"healthy"}If you are not using an explicit health_check config, Router also exposes:
curl http://localhost:4000/.well-known/apollo/server-healthFor Kubernetes readiness probe (matching this skill’s templates):
readinessProbe:
httpGet:
path: /health
port: 8088
initialDelaySeconds: 5
periodSeconds: 10Get more verbose output:
APOLLO_ROUTER_LOG=debug router --supergraph ./supergraph.graphqlLog levels:
error - Errors onlywarn - Warnings and errorsinfo - General information (default)debug - Detailed debug informationtrace - Very verbose tracing| Mistake | Solution |
|---|---|
| Introspection disabled in dev | Use --dev flag |
| Wrong subgraph URL in production | Use override_subgraph_url |
| CORS not configured | Add allowed origins |
| Timeout too short | Increase traffic_shaping.timeout |
| Missing APOLLO_KEY | Set environment variable |
| Wrong graph ref format | Use graph-id@variant |