Symfony: Environment Variable Not Found in CI

By Kaveh Alemi·Latchkey

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

Diagnose it: version, extensions, and limits

Terminal

php -v
php -m
php -i | grep -E "memory_limit|max_execution_time|error_reporting"

# a runner default is often far tighter than your local php.ini
php -d memory_limit=-1 vendor/bin/<tool>

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.

Frequently asked questions

What causes Symfony: environment variable not found in CI?

There are 2 common causes: the env var is unset in ci and no default for an optional variable. CI has no .env.local (gitignored) and the variable is not exported, so the %env(...)% reference cannot resolve.

How do I fix Symfony: environment variable not found in CI?

There are 3 fixes depending on which cause you have: provide the env var in ci, set a default with the env() processor, and provide build-time defaults in .env. Work through them in order, since the first is the most common.

What does Symfony: environment variable not found in CI actually mean?

A cache:clear, cache:warmup, or request in CI fails with "Environment variable not found: DATABASE_URL" (or similar).

How do I stop Symfony: environment variable not found in CI happening again?

Provide every %env(...)% variable the container needs in CI. The prevention section lists 3 changes that keep it from recurring.