Fix “The uploaded file exceeds the upload_max_filesize directive”

Checked 10 November 2026 · WordPress 7.1.4 · PHP 8.3.6 · MariaDB 10.11.14 · WP-CLI · Read time: 6 minutes

Case file

Symptom: Media upload fails with the upload_max_filesize error
Cause: PHP’s upload limit is 2M; the file is 2.2 MB
Fix: Raise upload_max_filesize and post_max_size to 64M in php.ini and reload PHP
Result: The same file uploads successfully

The break · What you need · The diagnosis · The fix · Verify · If that didn’t work · What happened · Where this came from

The break

When a file is uploaded through the Media Library, PHP checks its size before WordPress ever sees it. If the file is larger than the upload_max_filesize directive in php.ini, PHP rejects the upload and WordPress reports the rejection with that exact message. The PHP manual lists the directive’s default as 2M, which is why even a medium-sized photo can trigger it on a basic host.

This guide reproduces the break first. A disposable install ran with the PHP defaults — upload_max_filesize 2M and post_max_size 8M — and a real 2.2 MB JPEG was uploaded through the same upload handler the Media Library uses. The upload failed with the exact error, and after the limits were raised the same file uploaded fine.

What you need

Access to the PHP configuration: php.ini or .user.ini, your host’s PHP settings page, or .htaccess on an Apache host.
A way to reload PHP after the change — a PHP-FPM reload, an Apache restart, or your host’s reload button. Editing the file alone changes nothing until PHP reads it again.

The diagnosis

1. Confirm the symptom

Upload the file in Media > Add New and read the message. In the reproduction, the upload went through WordPress’s own upload handler and came back with this:

Output — upload of a 2,296,697-byte JPEG, limit 2M

{"success":false,"data":{"message":"The uploaded file exceeds the
upload_max_filesize directive in php.ini.","filename":"srm-3mb-photo.jpg"}}

Key result: the message names php.ini, not WordPress. That is the diagnosis: the limit lives in the PHP configuration, and the fix is there too.

2. Read the real limits

The Media Library shows the maximum upload size at the bottom of the uploader. For the exact numbers, check the PHP settings as WordPress sees them. In the reproduction:

Output — the limits in effect

upload_max_filesize=2M
post_max_size=8M
wp_max_upload_size=2 MB (2097152 bytes)

WordPress’s own cap, wp_max_upload_size(), is the smaller of the two PHP values — 2 MB here. The file was 2,296,697 bytes, just over it. The PHP manual states the rule the other way round: post_max_size must be larger than upload_max_filesize, because the file travels inside a POST request. Raise one without the other and the upload still fails.

Trap: WP-CLI’s wp media import will not reproduce this error. It uses the sideload path, which skips the browser-upload size check — the reproduction imported a 9 MB JPEG that way without any complaint. If you test the fix with WP-CLI, a passing import proves nothing. Test it with a real upload through the Media Library.

The fix

3. Raise both limits in php.ini

Edit php.ini — or the file your host uses for PHP settings, often .user.ini in the site root or the MultiPHP INI Editor in cPanel — and set both values:

Code — php.ini

upload_max_filesize = 64M
post_max_size = 64M

On an Apache host, the same change can go in .htaccess instead:

Code — .htaccess (Apache only)

php_value upload_max_filesize 64M
php_value post_max_size 64M

Then reload PHP so the new values take effect: restart PHP-FPM or Apache, or use the host’s reload button. In the reproduction, the same change was made by restarting the test server with the two values passed as PHP options — the equivalent of editing php.ini and reloading — and the limits were re-checked before the retest.

Trap: @ini_set( 'upload_max_filesize', '64M' ); in wp-config.php or functions.php does nothing. The PHP manual marks the directive as changeable only in php.ini, .htaccess and .user.ini — not at runtime — and the reproduction confirmed it: calling ini_set left the value at 2M. Several guides still suggest the ini_set version; it is the single most common reason this fix appears not to work.

Verify the upload works

Upload the same file again through the Media Library. In the reproduction, the identical 2.2 MB JPEG that failed before now succeeded:

Output — the same upload after the limits were raised to 64M

{"success":true,"data":{"id":8,"title":"srm-3mb-photo",
"filename":"srm-3mb-photo.jpg", ...}}

Step	Upload result
2.2 MB JPEG, limit 2M	Fails — “exceeds the upload_max_filesize directive”
Same file, limits raised to 64M	Succeeds — attachment created

Check the number shown at the bottom of Media > Add New after the reload: it should read the new limit. If it still shows the old one, PHP has not reloaded — the edit is not in effect yet.

If that didn’t work

Ask the host

Some shared hosts do not let you edit php.ini or use php_value in .htaccess. The official common-errors guide says the same about the memory limit: if you are unfamiliar with the file, or your host prevents the change, contact the host and ask them to raise the two values. Give them the exact numbers — “please raise upload_max_filesize to 64M and post_max_size to 64M” — so the request cannot be misread.

Check post_max_size first if the error is different

If the upload fails with no message at all, or the whole form seems to vanish, the file may be larger than post_max_size rather than upload_max_filesize. When the POST body exceeds post_max_size, PHP drops the entire request, so WordPress never even sees a file to reject. The fix is the same pair of settings — but post_max_size is the one that has to grow.

What happened

A 2.2 MB JPEG was larger than PHP’s 2M upload limit, so PHP rejected it and WordPress reported the upload_max_filesize error. The limits were raised to 64M in the PHP configuration and PHP was reloaded, and the same file uploaded successfully. An ini_set shortcut was tested and confirmed not to work, and WP-CLI import was confirmed not to reproduce the error at all.

Where this came from

upload_max_filesize as the maximum size of an uploaded file, its 2M default, its PHP_INI_PERDIR changeability, and the rule that post_max_size must be larger than it come from Description of core php.ini directives — The PHP Manual.
Raising a limit by editing php.ini, and contacting the host when the file is unfamiliar or the host prevents the change, come from Common WordPress errors — WordPress.org.
The exact error message and the upload result come from the reproduction itself: WordPress’s upload handler returned the message for a 2.2 MB file at a 2M limit, and success after the limits were raised to 64M.