envoy --mode validate: Lint Envoy Config in CI
envoy --mode validate loads an Envoy bootstrap config, checks it fully, and exits 0 if valid or non-zero if not, without ever binding a port.
When you hand-write or template Envoy config (gateways, custom proxies, filters), this is the offline gate that catches a broken config before it ships.
What it does
envoy --mode validate runs Envoys normal config load path against the file given with -c: it parses the bootstrap, validates every listener, cluster, and filter chain against the proto schema, and reports the first error. Because it exits immediately, it is safe to run in CI without starting a real proxy.
Common usage
envoy --mode validate -c envoy.yaml
# validate a JSON bootstrap
envoy --mode validate -c bootstrap.json
# inside the official image
docker run --rm -v $PWD:/cfg envoyproxy/envoy:v1.30-latest \
envoy --mode validate -c /cfg/envoy.yamlOptions
| Flag | What it does |
|---|---|
| --mode validate | Validate the config and exit, do not serve |
| -c, --config-path <file> | Path to the bootstrap config (YAML or JSON) |
| --config-yaml <inline> | Inline YAML overrides merged on top of -c |
| -l, --log-level <level> | Log verbosity during validation |
In CI
Add envoy --mode validate -c to the lint stage for any repo that ships Envoy config. Use the pinned envoyproxy/envoy image so the validator matches the Envoy version you deploy; a config valid on one version can be rejected on another as fields change.
Common errors in CI
"Config failed to validate: ..." with a JSON path shows exactly which field is wrong, for example "Proto constraint validation failed ... value must be greater than 0". "Unable to parse ... as ..." means a YAML/JSON syntax error. "unknown field \"...\"" means a typo or a field from a different Envoy version than the validating binary.