symfony/http-foundation · error · InvalidArgumentException

An uploaded file must be an array or an instance of…

Error message

An uploaded file must be an array or an instance of UploadedFile.

What it means

An InvalidArgumentException from a type guard in FileBag::set(). Every value stored in the file bag must be either a nested array (for PHP's multi-dimensional $_FILES structure) or an UploadedFile instance; any other value (string, int, object of another class) passed via set(), add(), replace() or the constructor is rejected before storage.

Solutions

1. Pass only arrays or UploadedFile instances into FileBag::set/add/replace or its constructor
2. Convert raw $_FILES-style arrays of file metadata into UploadedFile objects before injecting them
3. Validate the value type (is_array($v) || $v instanceof UploadedFile) before calling set()

When it happens

Trigger: Thrown at FileBag.php:43 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at FileBag.php:43

    public function set(string $key, mixed $value): void
    {
        if (!\is_array($value) && !$value instanceof UploadedFile) {
            throw new \InvalidArgumentException('An uploaded file must be an array or an instance of UploadedFile.');
        }

        parent::set($key, $this->convertFileInformation($value));
    }

    public function add(array $files = []): void
    {
        foreach ($files as $key => $file) {
            $this->set($key, $file);
        }
    }

View on GitHub (pinned to 5aea19cd67)