sebastianbergmann/phpunit · error · InvalidPhptFileException

File referenced by --FILE_EXTERNAL-- section is empty

Error message

File referenced by --FILE_EXTERNAL-- section is empty

What it means

ensureCodeIsNotEmpty() returns early when a non-empty FILE section exists; parseExternal() has already loaded the --FILE_EXTERNAL-- target's contents into sections['FILE']. When the resolved code section is FILE_EXTERNAL and that content is empty, InvalidPhptFileException('File referenced by --FILE_EXTERNAL-- section is empty') is thrown: the external file exists and is readable, but contributes no code.

Source

Thrown at src/Runner/Phpt/Parser.php:335

        }

        return $found[0];
    }

    /**
     * @param array<non-empty-string, string> $sections
     * @param non-empty-string                $codeSection
     *
     * @throws InvalidPhptFileException
     */
    private function ensureCodeIsNotEmpty(array $sections, string $codeSection): void
    {
        if (isset($sections['FILE']) && $sections['FILE'] !== '') {
            return;
        }

        if ($codeSection === 'FILE_EXTERNAL') {
            throw new InvalidPhptFileException(
                'File referenced by --FILE_EXTERNAL-- section is empty',
            );
        }

        throw new InvalidPhptFileException(
            sprintf(
                '--%s-- section is empty',
                $codeSection,
            ),
        );
    }
}

View on GitHub (pinned to f123cdb2a2)

Solutions

1. Put the intended PHP code into the file referenced by --FILE_EXTERNAL--.
2. If fixtures are generated at build time, make the generator fail the build on empty output instead of writing an empty file.

Example fix

# before: hello.php is empty (0 bytes)
--FILE_EXTERNAL--
hello.php

# after: hello.php contains
<?php echo 'Hello';

// before running PHPT tests, verify FILE_EXTERNAL targets are non-empty
foreach (glob('tests/*.phpt') as $phpt) {
    $body = (string) file_get_contents($phpt);
    if (preg_match('/--FILE_EXTERNAL--\R\s*(\S+)/', $body, $m) === 1) {
        $target = dirname($phpt) . DIRECTORY_SEPARATOR . $m[1];
        if (trim((string) file_get_contents($target)) === '') {
            throw new RuntimeException("Empty FILE_EXTERNAL fixture: {$target}");
        }
    }
}

When it happens

Trigger: --FILE_EXTERNAL-- points at a zero-byte file, or a file containing only whitespace/newlines, so after loading there is no code to execute.

Common situations: Placeholder fixtures committed empty; a fixture script truncated during a bad merge; a generation step that failed silently before the test run.

Related errors

• Could not load --%s-- %s for PHPT file
• --%s-- is not a valid PHPT section
• --%s-- section occurs more than once
• PHPT file must not contain text before its first section (li
• PHPUnit does not support PHPT --%s-- sections

AI-assisted analysis of sebastianbergmann/phpunit@f123cdb2a2 (2026-08-23). Data as JSON: /api/errors/08296cc538d6bf6f. Report an issue: GitHub.