What is the default error propagation mode?

The default mode is wrapped. Subgraph errors are encapsulated in a generic "Failed to fetch from Subgraph" message. Error details appear in extensions.errors. The default allowed_extension_fields is ["code"].

How do I prevent any subgraph error details from reaching clients?

In wrapped mode, set omit_extensions: true. Clients receive only the generic "Failed to fetch from Subgraph" message with no extension data. This is the highest security setting.

My client uses error codes for error handling. How do I forward only the code field?

This is the default behavior. Wrapped mode with allowed_extension_fields: ["code"] forwards only the "code" extension field while blocking all other extension data. The "code" value appears in the extensions.errors array inside the wrapped error.

What is the difference between wrapped and pass-through mode?

In wrapped mode, the subgraph error is placed inside a generic outer error object. Extensions from the subgraph error appear in extensions.errors. In pass-through mode, errors are forwarded directly as received from the subgraph, with optional field filtering applied.

Does omit_extensions override allowed_extension_fields?

Yes. Setting omit_extensions: true prevents any extension fields from reaching clients, regardless of what is configured in allowed_extension_fields or allow_all_extension_fields.

What happens to errors in development mode?

In dev_mode, the router is configured to be as verbose as possible and exposes additional details about subgraph errors. Ensure dev_mode: false is set before deploying to production.

Subgraph Error Propagation for GraphQL | Cosmo by WunderGraph

The problem

Subgraph errors reveal more than clients need to know

Raw subgraph errors contain internal details that clients have no use for and attackers can exploit.

Subgraph errors contain internal details

Database error messages, internal service names, stack traces, and infrastructure details appear in subgraph errors. Forwarding these to clients exposes the internals of your architecture.

Hiding all errors blocks client error handling

Some clients rely on extension fields like "code" to implement error handling logic. Stripping all error details breaks that logic without providing any visible alternative.

Development mode exposes everything by default

In dev_mode, the router is as verbose as possible and exposes additional subgraph error details. Teams that forget to disable dev_mode in production ship with that extra exposure.

Our solution

Configurable control over what errors reveal

Choose a mode, whitelist the extension fields clients need, and strip everything else. The defaults are tuned for production security with client error handling preserved.

From raw error to filtered response

Choose wrapped mode (default) or pass-through mode for error handling.
In wrapped mode, subgraph errors are encapsulated in a generic "Failed to fetch from Subgraph" message. Subgraph error details appear in extensions.errors.
Configure allowed_extension_fields to whitelist specific extension fields (e.g., "code") while blocking all others. The default allowlist is ["code"].
Set omit_extensions: true for maximum security — no extension fields reach clients.
In pass-through mode, errors are forwarded directly. Use allowed_extension_fields and omit_locations: true to control what is included.
Set attach_service_name: true to include the subgraph name in error responses, or leave it off to hide subgraph identity.

In dev_mode, the router exposes additional subgraph error details. Ensure dev_mode: false in production.

Error propagation

Before & After

Before Cosmo	With Cosmo
Raw subgraph errors including stack traces forwarded to clients	Wrapped errors with only approved extension fields
Internal service names visible in all error responses	attach_service_name controls whether the name appears
All extension fields forwarded or none	Whitelist specific fields with allowed_extension_fields
Subgraph line/column locations in error responses	omit_locations: true strips irrelevant internal locations

Wrapped mode

Generic outer error, filtered inner details

The client receives a generic "Failed to fetch from Subgraph 'x'." error. Subgraph error details — filtered by allowed_extension_fields — appear in extensions.errors. Set omit_extensions: true to return the generic message only.

How subgraph error propagation works in Cosmo Router

01

Wrapped (default) or pass-through.

Choose mode

Wrapped mode (default) encapsulates subgraph errors in a generic message. The original error details appear in extensions.errors in the client response. Pass-through mode forwards errors directly to the client with configurable filtering.

02

Allowlist, all, or none.

Filter extensions

Set allowed_extension_fields to a list of extension keys clients are allowed to see. The default is ["code"]. Set allow_all_extension_fields: true to forward everything. Set omit_extensions: true to block all extension fields — this overrides both.

03

Service name: on or off.

Control service names

Set attach_service_name: true to include the subgraph name in error extensions. This helps client-side routing and debugging but reveals which subgraph produced the error. Leave it off to hide subgraph identity from clients.

04

Strip internal locations.

Strip locations

Subgraph errors include line/column locations internal to the subgraph implementation and not relevant to clients. Set omit_locations: true to remove them. The option works in both wrapped and pass-through mode.

Error controls

Security and client usability, both

Forward error codes for client handling. Strip stack traces and internal names.

Wrapped mode (default)

Subgraph errors are placed inside a generic outer error. The "code" extension field is forwarded by default. All other internal details are blocked. Set omit_extensions: true to return only the generic message.

Pass-through mode

Errors are forwarded directly as received from the subgraph. Use allowed_extension_fields to control which extension keys are included. Use omit_locations: true to strip subgraph-internal line/column locations.

Extension field allowlisting

specify allowed_extension_fields with only the keys clients need. The "code" field is the most common use case. Set allow_all_extension_fields: true for full transparency in internal APIs. omit_extensions overrides both.

Service name control

attach_service_name: true includes the subgraph name in error extensions. This aids debugging and client-side routing. Leave it off to prevent clients from learning which subgraph produced each error.

Control what your errors reveal

Configure subgraph_error_propagation in router YAML. Defaults are production-safe.

Start Free Read the Docs

Stop internal errors from reaching your clients