Development Mode for GraphQL Federation

Start building against the router in one line of config. dev_mode: true turns on human-readable logs, detailed subgraph error output, and automatic localhost fallback inside Docker.

Local federation should not fight you

Defaults that protect production often erase the signal you need on your laptop. Docker networking and half-configured YAML make it worse.

Production defaults hide what you need to see

Structured JSON logs and sanitized errors are useful in production, but harder to debug locally. Reading a 400-line JSON blob for a single request is not how debugging should start.

Inside a container, localhost is not your host

A subgraph URL like http://localhost:4001 works on your laptop because localhost is your machine. From the router running in Docker, the same URL still means “this container,” so the process never reaches services on your Mac or Windows host. That mismatch trips teams constantly during local federation.

Development settings drift over time

Teams often end up maintaining separate debug flags, error settings, and logging overrides across environments. Months later, nobody remembers why stack traces appear in one setup but not another.

One line of config enables development-friendly router defaults

Cosmo Router development mode bundles the router settings most teams enable during local development into a single preset, so developers can debug locally without hand-configuring logging, error propagation, and Docker networking behavior.

What happens when the preset is on

1. Set dev_mode: true in the router config. At startup, the router loads a development-focused preset instead of requiring individual debugging settings to be configured manually.
2. The preset bundles settings you would otherwise flip one by one. It disables JSON logs, enables full subgraph error propagation (HTTP status codes, GraphQL locations, and stack trace fields when the subgraph sends them), and turns on Advanced Request Tracing (ART) for local development.
3. When a subgraph URL uses localhost and the connection fails inside Docker, the router retries against host.docker.internal automatically (unless you disable the fallback).
4. Config changes reload automatically during development, so teams can iterate without restarting the router.
5. You spend time building, not configuring multiple settings manually, and you remove or set dev_mode: false before production so debug output does not appear in production responses.

Before & After

What dev_mode: true enables

dev_mode: true is a preset equivalent to:

• json_log: false
• subgraph_error_propagation:
  • propagate_status_codes: true
  • omit_locations: false
  • allowed_extension_fields: ["code", "stacktrace"]

Plus: Advanced Request Tracing (ART) is enabled automatically in local development environments, as well as automatic Docker-to-localhost fallback.

Using development mode

Flip the toggle

Add dev_mode: true to the router config and start the router locally.

Same development settings every time the router starts

At startup the preset applies in one go: readable logs, richer subgraph errors, local ART, and the Docker fallback.

See failures where they happen.

Run queries against the router locally. Errors become easier to debug, logs are readable in the terminal, and Docker localhost failures recover automatically.

Production configs stay explicit.

Disable development mode in production configs to keep production logging and error responses sanitized.

Where teams lean on dev mode

First-time router setup

A new developer pulls the repo, starts the router with dev_mode: true. Within a minute they have readable logs, working Docker networking, and expanded error output, none of which they had to configure.

Debugging a failing federated query

A query returns an error. Development mode surfaces the subgraph's HTTP status code, the error location in the query, and the stack trace when the subgraph provides one.

Docker Compose with local subgraphs

Router in Docker; subgraphs on the host at localhost:4001 and localhost:4002. If localhost fails in-container, retries use host.docker.internal:4001.