symfony/http-foundation · error · InvalidArgumentException

The disposition must be either

Error message

The disposition must be either "%s" or "%s".

What it means

HeaderUtils::makeDisposition() only accepts two disposition types: self::DISPOSITION_ATTACHMENT ('attachment') and self::DISPOSITION_INLINE ('inline'), compared strictly with in_array(..., true). Any other string (typo, capitalized, empty) throws this InvalidArgumentException, because RFC 6266 defines only these two disposition types for the Content-Disposition header.

Solutions

1. Use HeaderUtils::DISPOSITION_ATTACHMENT or HeaderUtils::DISPOSITION_INLINE constants instead of literal strings
2. Check the exact spelling and case: only lowercase 'attachment' and 'inline' are valid
3. If the value comes from config/user input, whitelist and map it to the two allowed constants before calling
4. Wrap the call in try/catch InvalidArgumentException and default to DISPOSITION_ATTACHMENT

Example fix

// before
HeaderUtils::makeDisposition('attachment', 'report.pdf'); // or 'ATTACHMENT'
// after
use Symfony\Component\HttpFoundation\HeaderUtils;
HeaderUtils::makeDisposition(HeaderUtils::DISPOSITION_ATTACHMENT, 'report.pdf');

if (!in_array($disposition, [HeaderUtils::DISPOSITION_ATTACHMENT, HeaderUtils::DISPOSITION_INLINE], true)) {
    $disposition = HeaderUtils::DISPOSITION_ATTACHMENT;
}

function isValidDisposition(?string $d): bool {
    return $d === HeaderUtils::DISPOSITION_ATTACHMENT || $d === HeaderUtils::DISPOSITION_INLINE;
}

try {
    $header = HeaderUtils::makeDisposition($disposition, $filename);
} catch (\InvalidArgumentException $e) {
    $header = HeaderUtils::makeDisposition(HeaderUtils::DISPOSITION_ATTACHMENT, $filename);
}

When it happens

Trigger: Calling HeaderUtils::makeDisposition() with a $disposition argument other than the exact strings 'attachment' or 'inline' — e.g. 'attachement' (typo), 'ATTACHMENT' (wrong case), 'attachment ' (trailing space), or a variable holding an unexpected value.

Common situations: Typing the disposition constant as a raw string instead of using the class constants HeaderUtils::DISPOSITION_ATTACHMENT / DISPOSITION_INLINE; building the disposition dynamically from user input or config; upgrading Symfony where the check became strict (===) so previously-tolerated case variants now fail.

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

• The filename fallback cannot contain the "%" character.
• The filename fallback must only contain ASCII characters.
• The filename and the fallback cannot contain the "/" and…
• The "sameSite" parameter value is not valid.
• The cookie name " " uses a reserved prefix, which requires…

AI-assisted analysis of symfony/http-foundation@5aea19cd67 (2026-09-13). Data as JSON: /api/errors/98677b2aeae7216a. Report an issue: GitHub.

Appendix: source

Thrown at HeaderUtils.php:168

    }

    /**
     * Generates an HTTP Content-Disposition field-value.
     *
     * @param string $disposition      One of "inline" or "attachment"
     * @param string $filename         A unicode string
     * @param string $filenameFallback A string containing only ASCII characters that
     *                                 is semantically equivalent to $filename. If the filename is already ASCII,
     *                                 it can be omitted, or just copied from $filename
     *
     * @throws \InvalidArgumentException
     *
     * @see RFC 6266
     */
    public static function makeDisposition(string $disposition, string $filename, string $filenameFallback = ''): string
    {
        if (!\in_array($disposition, [self::DISPOSITION_ATTACHMENT, self::DISPOSITION_INLINE], true)) {
            throw new \InvalidArgumentException(\sprintf('The disposition must be either "%s" or "%s".', self::DISPOSITION_ATTACHMENT, self::DISPOSITION_INLINE));
        }

        if ('' === $filenameFallback) {
            $filenameFallback = $filename;
        }

        // filenameFallback is not ASCII.
        if (!preg_match('/^[\x20-\x7e]*$/', $filenameFallback)) {
            throw new \InvalidArgumentException('The filename fallback must only contain ASCII characters.');
        }

        // percent characters aren't safe in fallback.
        if (str_contains($filenameFallback, '%')) {
            throw new \InvalidArgumentException('The filename fallback cannot contain the "%" character.');
        }

        // path separators aren't allowed in either.
        if (str_contains($filename, '/') || str_contains($filename, '\\') || str_contains($filenameFallback, '/') || str_contains($filenameFallback, '\\')) {

View on GitHub (pinned to 5aea19cd67)