EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/docs/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
Hot Reload
Zero-downtime schema updates
Hot reloading enables the router to update its supergraph schema without restarting, providing zero-downtime schema updates.
Before enabling hot reload, consult the support matrix to ensure your schema source is supported, and carefully consider the performance considerations.
Hot reload support matrix
| Schema Source | Hot Reload Support | Notes |
|---|---|---|
| Apollo Uplink | 🟢 Yes | Automatically polls every 10 seconds for updates |
| Local file | 🟢 Yes | Requires --hot-reload flag or APOLLO_ROUTER_HOT_RELOAD=true |
| Remote URLs | ❌ No | Schema fetched once at startup |
Performance considerations
When using hot reloading for supergraph schemas, be aware of the following performance considerations:
Schema reloading overhead: Each schema reload requires parsing and validation, which temporarily increases CPU usage.
Request handling: During reload, new requests might experience slight latency increases while the new schema is being processed.
Memory usage: The router maintains both the old and new schema briefly during reload, temporarily increasing memory usage.
Configure reload retries
When a reload fails — for example, because a transient network error prevents the router from fetching a persisted query manifest from Uplink — the router automatically retries instead of continuing to serve traffic on the previous configuration indefinitely.
Tune this behavior with the reload configuration section:
1reload:
2 # Maximum number of retry attempts after a failed reload.
3 # 0 disables automatic retries. null allows unlimited retries.
4 # Default: 5
5 max_retries: 5
6
7 # Base delay between retry attempts. A random jitter of up to 25% is added
8 # to spread retries across multiple router instances.
9 # Default: 10s
10 retry_delay: 10sThe retry budget is reset whenever the router receives a new reload trigger — a new schema or license from Uplink, a configuration or rhai script file change, or an explicit reload signal — so any new change will always get a fresh set of attempts even if previous retries were exhausted.
The router only retries failures that a later attempt might resolve. Some reloads fail for a reason that can't change on its own: a schema that doesn't parse, a configuration that isn't valid for your license, or a schema that uses preview features your configuration doesn't enable. The router doesn't spend retries on these. It keeps serving the previous schema, configuration, and license, and waits for your next update, which gets a fresh set of attempts.
The apollo.router.state.reload.attempt metric counts reload attempts. Its is_success attribute tells you whether the reload built, and error_kind tells you why it didn't, so you can distinguish a router that's still retrying (transient) from one that's waiting for you to publish a fix (permanent).
Production recommendations
For production deployments with high traffic:
Monitor during reloads: If using hot reload, monitor CPU, memory, and latency metrics during schema updates.
Schedule updates: Plan schema updates during lower-traffic periods when using hot reload.
Use blue/green deployments: For production deployments requiring schema updates, use blue/green deployment strategies with OCI digest references.