GraphQL introspection: potential impacts and fallback options

Describes what can change when introspection is disabled and the available recovery options if disabling introspection causes issues.

Potential impacts

Disabling introspection affects only schema discovery via introspection fields such as schema and type. Consider the following impacts before you set introspection: false.

Developer tooling: GraphQL IDE features that rely on introspection (for example, schema explorers, documentation panels, or editor auto-complete) might stop working or become limited.
Client behavior: Any client workflow that depends on runtime schema discovery through schema/ type will not be able to retrieve schema details from the endpoint after introspection is disabled.
Security considerations: Disabling introspection can reduce schema discoverability from the endpoint. However, schema information can often be inferred through other means (for example, inspection of browser-based client code or network traffic). The decision to disable introspection should be based on your organization’s risk assessment and operational requirements.
Performance: Most environments should not see a meaningful performance change for standard business queries and mutations. The primary change is that introspection requests are blocked.

Note: The default remains introspection: true for backward compatibility. Some customers disable introspection based on internal policy even if they do not expect a significant security difference for browser-based public clients.

Fallback options and recovery

If disabling introspection causes issues (for example, IDE tooling failures), use one of the following recovery options.

Rollback (re-enable introspection): Update your override configuration file (opts.yaml) to re-enable introspection, then restart the GraphQL server.
```
introspection: true
```
Remove the override: Remove the custom override file from /SETUP/Custom/opts so the GraphQL server uses the default configuration, then restart the GraphQL server.
Environment-specific configuration: Keep introspection: true in non-production environments (development/test) to support schema exploration, and set introspection: false in production if required by your security policy.
Phased rollout: Apply introspection: false in a lower environment first, validate key client flows and operational tooling, and then promote the setting to production.
Layered controls: If the main goal is to reduce exposure, consider restricting access to the GraphQL endpoint (for example, gateway rules, allowlists, and authentication/authorization where applicable) instead of, or in addition to, disabling introspection.

For information about where custom configuration files are placed, see HCL Commerce GraphQL extensions and Changing GraphQL server configuration.