Symfony KernelTestCase "bootKernel()" fails in the test env in CI

A test extending KernelTestCase calls bootKernel() and the kernel fails to boot. In CI this is almost always a missing env var (APP_SECRET, DATABASE_URL), a wrong APP_ENV, or KERNEL_CLASS not resolvable, since the test env differs from local dev.

What this error means

PHPUnit fails inside a test extending Symfony\Bundle\FrameworkBundle\Test\KernelTestCase with an exception thrown from bootKernel(), often an "Environment variable not found" or "You must set the KERNEL_CLASS ...".

Symfony

LogicException: You must set the KERNEL_CLASS environment variable to the fully-qualified
class name of your Kernel in phpunit.xml.dist / phpunit.xml or override the
KernelTestCase::createKernel() or KernelTestCase::getKernelClass() method.

Common causes

The test env is missing required variables

The kernel resolves %env(...)% while booting. If .env.test or the job env lacks APP_SECRET/DATABASE_URL, boot fails at the first unresolved variable.

KERNEL_CLASS or APP_ENV is not configured for tests

PHPUnit did not set KERNEL_CLASS, or APP_ENV is not test, so KernelTestCase cannot locate or configure the kernel.

How to fix it

Configure the test env and required variables

Set APP_ENV=test and KERNEL_CLASS in phpunit.xml.dist.
Provide APP_SECRET and DATABASE_URL in .env.test (or the job env).
Re-run PHPUnit so bootKernel() finds a bootable configuration.

phpunit.xml.dist

<!-- phpunit.xml.dist -->
<php>
  <server name="APP_ENV" value="test" force="true" />
  <server name="KERNEL_CLASS" value="App\Kernel" />
</php>

Load .env.test values in the bootstrap

Ensure tests/bootstrap.php loads dotenv so variables are present before the kernel boots.

tests/bootstrap.php

// tests/bootstrap.php
if (method_exists(Dotenv::class, 'bootEnv')) {
    (new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
}

How to prevent it

Set APP_ENV=test and KERNEL_CLASS in phpunit.xml.dist.
Keep .env.test complete so the test kernel always boots.
Load dotenv in tests/bootstrap.php before any kernel boot.