Is dev_mode: true safe to use in production?

No. It exposes full error details including stack traces, HTTP status codes, and error locations — information you don't want leaking to external clients.

Can I enable Advanced Request Tracing (ART) in production?

Yes, but it requires additional security configuration. In dev mode, ART is enabled without any security headers. In production you'd need to configure that security yourself after disabling dev mode.

What does the Cosmo Router Docker localhost fallback actually do?

When the router is running inside Docker and a connection to localhost fails, it automatically retries the request using host.docker.internal instead. This lets you connect to subgraphs running on your host machine without extra network config.

Can I combine dev mode with custom production error-propagation settings?

No. To configure individual error-propagation settings (like propagate_status_codes or allowed_extension_fields), you need to disable dev mode first and then set those values manually.

How do I disable the Docker localhost fallback in the Router?

Set the environment variable LOCALHOST_FALLBACK_INSIDE_DOCKER=false.

GraphQL Router Development Mode | Cosmo by WunderGraph

The problem

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.

Our solution

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

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.
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.
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).
Config changes reload automatically during development, so teams can iterate without restarting the router.
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.

One line for local dev. Explicit config for production.

Development mode

Before & After

Before Cosmo	With Cosmo
Five separate toggles to get useful dev output	`dev_mode: true` flips them all at once
JSON logs that are hard to read during debugging	Human-readable, terminal-friendly logs
Sanitized errors, unclear why a query failed	Expanded subgraph error context: status codes, locations, and stack traces when available
Docker-to-localhost networking needs manual setup	Automatic fallback to `host.docker.internal` on failure

Preset

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

01

One key. One preset.

Flip the toggle

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

02

Same development settings every time the router starts.

Preset applies when the router starts

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

03

See failures where they happen.

Work against the router

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

04

Production configs stay explicit.

Disable for production

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

Use cases

Where teams lean on dev mode

Onboarding, debugging, and Compose-first workflows, without hand-tuning every flag.

First-time router setup

Onboarding

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

Errors

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

Networking

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

Important notes

Limits

Disable dev_mode before turning on production-only features explicitly.
Optional: LOCALHOST_FALLBACK_INSIDE_DOCKER=false turns off Docker localhost fallback.
Details and limits: Config Hot Reload.

Ship local-first, lock down prod

One YAML line for development defaults, then explicit config for production.

Start Free Read the Docs

Development Mode for GraphQL Federation