Symfony: Environment Variable Not Found in CI

Symfony resolves %env(X)% references during container compilation and at runtime. When the variable is not set, has no .env value, and no default is provided, Symfony throws "Environment variable not found", failing cache warmup or the request in CI.

What this error means

A cache:clear, cache:warmup, or request in CI fails with "Environment variable not found: DATABASE_URL" (or similar). The app runs locally where .env/.env.local defines the variable.

php

In EnvVarProcessor.php line 100:
  Environment variable not found: "DATABASE_URL".
# during bin/console cache:clear --env=prod

Common causes

The env var is unset in CI

CI has no .env.local (gitignored) and the variable is not exported, so the %env(...)% reference cannot resolve.

No default for an optional variable

A reference to a variable that is sometimes optional has no default value, so its absence is fatal instead of falling back.

How to fix it

Provide the env var in CI

Export the variable (dummy values are fine for a build-only step).

php

export APP_ENV=prod
export DATABASE_URL="mysql://user:pass@127.0.0.1:3306/app"
php bin/console cache:clear --env=prod

Set a default with the env() processor

Give optional variables a default so their absence is not fatal.

php

# config/services.yaml
parameters:
    app.timeout: '%env(default:app_default_timeout:int:APP_TIMEOUT)%'

Provide build-time defaults in .env

Define non-secret defaults in the committed .env (not .env.local).
Set secrets via CI env/secrets, not committed files.
Run bin/console debug:dotenv to see which values resolve.

How to prevent it

Provide every %env(...)% variable the container needs in CI.
Give optional env vars defaults via the default: processor.
Keep non-secret defaults in committed .env; inject secrets via CI.