Envoy "error initializing configuration" (Proto) in CI

By Daniel Zoghalchali·Latchkey

Envoy parsed the bootstrap YAML into its protobuf config schema and a field did not match: an unknown field, a wrong type, or a misplaced key. Envoy refuses to start on an invalid config.

What this error means

Envoy exits with "error initializing configuration" and a protobuf message such as "Unknown field" or "INVALID_ARGUMENT" naming the bad field.

[critical] error initializing configuration '/etc/envoy/envoy.yaml':
Unknown field in: {"listner": ...} (did you mean "listeners"?)

Common causes

A field name does not exist in the xDS schema

A typo (listner) or a field from a different API version is not part of the protobuf message, so parsing fails.

The config targets a different Envoy API version

A key valid in one xDS version was moved or renamed, so the running Envoy version rejects it.

How to fix it

Fix the field to match the schema

1. Read the "Unknown field" message; it names the offending key and often a suggestion.
2. Correct the field name or move it to the right message in the config.
3. Re-validate against the Envoy version you deploy.

static_resources:
  listeners:
    - name: listener_0
      address:
        socket_address: { address: 0.0.0.0, port_value: 10000 }

Validate against the deployed Envoy version

Run validate with the same Envoy image you ship so version-specific schema mismatches surface in CI.

docker run --rm -v "$PWD:/cfg" envoyproxy/envoy:v1.31-latest \
  envoy --mode validate -c /cfg/envoy.yaml

How to prevent it

• Validate config with the exact Envoy version you deploy.
• Track xDS field renames when upgrading Envoy.
• Keep bootstrap config under review for typos and stray fields.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation