PHPOffice/PHPWord · error · Exception

Invalid header/footer type.

Error message

Invalid header/footer type.

What it means

Section::addHeaderFooter() builds a Header/Footer container for the given type, but only Header::AUTO, Header::FIRST and Header::EVEN (and the footer equivalents) are recognized; anything else falls through to a generic PhpOffice\PhpWord\Exception\Exception 'Invalid header/footer type.'. It is an internal whitelist check on the container type constant.

Solutions

1. Use the class constants: Section::addHeader(Header::AUTO) (or FIRST / EVEN).
2. Fix typos — valid values are exactly 'AUTO', 'FIRST', 'EVEN'.
3. Validate/whitelist a config value against these constants before passing it in.
4. Catch PhpWord Exception around addHeader/addFooter for user-driven configuration.

Example fix

// before
$section->addHeader('DEFAULT');
// after
$section->addHeader(Header::AUTO);

$allowed = [\PhpOffice\PhpWord\Element\Header::AUTO, \PhpOffice\PhpWord\Element\Header::FIRST, \PhpOffice\PhpWord\Element\Header::EVEN];
if (!in_array($type, $allowed, true)) { throw new DomainException('Bad header type'); }

function isValidHeaderFooterType(string $t): bool { return in_array($t, ['AUTO', 'FIRST', 'EVEN'], true); }

try { $hdr = $section->addHeader($type); } catch (\PhpOffice\PhpWord\Exception\Exception $e) { $hdr = $section->addHeader(Header::AUTO); }

When it happens

Trigger: Calling $section->addHeader('FOO') or addFooter with a string other than 'AUTO'/'FIRST'/'EVEN' (the Header/Footer constants), often from a typo or dynamic value.

Common situations: Passing 'DEFAULT' instead of 'AUTO', mixing up header/footer type names, or mapping document settings to header types without validating the mapping.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid value, on of ' . implode(', ', $position) . '…
• Invalid value, on of ' . implode(', ', $restartNumbers) . '…
• Invalid value, dirty or clean possible
• Invalid value, alignments of ' . implode(', '…
• Cannot set a Comment on a Comment

AI-assisted analysis of PHPOffice/PHPWord@aef95c0415 (2026-09-14). Data as JSON: /api/errors/04f6d279e104d501. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/Element/Section.php:214

    private function addHeaderFooter($type = Header::AUTO, $header = true)
    {
        $containerClass = substr(static::class, 0, strrpos(static::class, '\\') ?: 0) . '\\' .
            ($header ? 'Header' : 'Footer');
        $collectionArray = $header ? 'headers' : 'footers';
        $collection = &$this->$collectionArray;

        if (in_array($type, [Header::AUTO, Header::FIRST, Header::EVEN])) {
            $index = count($collection);
            /** @var AbstractContainer $container Type hint */
            $container = new $containerClass($this->sectionId, ++$index, $type);
            $container->setPhpWord($this->phpWord);

            $collection[$index] = $container;

            return $container;
        }

        throw new Exception('Invalid header/footer type.');
    }
}

View on GitHub (pinned to aef95c0415)