Troubleshooting · Explainer
What Causes "Uploaded File Exceeds upload_max_filesize" in WordPress?
Short answer
The error means the file is larger than the upload_max_filesize limit set in PHP, so WordPress refuses it before the upload finishes. The limit comes from PHP, not WordPress, and the real ceiling is the smaller of upload_max_filesize and post_max_size, so both values must rise together.
Key takeaways
- The upload limit comes from PHP, not WordPress, and wp_max_upload_size returns the smaller of upload_max_filesize and post_max_size.
- PHP's own defaults are 2M for upload_max_filesize, 8M for post_max_size, and 128M for memory_limit as of November 2026.
- Raising only upload_max_filesize leaves the limit unchanged when post_max_size is still smaller.
- Nginx rejects oversized requests with a 413 error before PHP sees them, and its client_max_body_size default is 1m.
- A host can cap the upload size, and no plugin or php.ini edit can pass a hard server cap.
What does “Uploaded File Exceeds upload_max_filesize” mean?
The error means the file is larger than the upload_max_filesize limit in PHP, so the upload is refused.
WordPress shows the message in the Media Library when a file passes the size limit, and it can also appear when a theme or plugin upload is too large. The limit is a PHP setting, not a WordPress setting, so no option inside WordPress changes it on its own.
Developer.WordPress.org's wp_max_upload_size page says the function determines the maximum upload size allowed in php.ini. It reads upload_max_filesize and post_max_size, converts both to bytes, and returns the smaller of the two through the upload_size_limit filter.
The same function has been in WordPress core since version 2.5.0, as the reference page shows. Full fix steps are in the guide to fix “Uploaded File Exceeds upload_max_filesize”.
The number printed in the Media Library, such as “Maximum upload file size: 8 MB”, is the result of that function, so it changes only when the PHP values change.
What sets the upload limit on a WordPress site?
Three PHP settings set the limit, and the smallest one wins.
PHP's manual lists core php.ini directives, and the upload_max_filesize entry shows a 2M default. The post_max_size entry says the value must be larger than upload_max_filesize when uploading large files, and that memory_limit should be larger than post_max_size.
| Setting | What it caps | PHP default as of November 2026 |
|---|---|---|
| upload_max_filesize | One single file | 2M |
| post_max_size | The whole request, file plus form fields | 8M |
| memory_limit | Memory one script may use | 128M |
Hosts usually raise these defaults: many shared hosts set upload_max_filesize between 8M and 64M. The Media Library number still comes from the smaller of the two file settings, so raising only one of them leaves the limit where it was.
The WordPress minimum requirements guide lists the current PHP versions a host should run.
Why does raising upload_max_filesize alone not work?
Raising upload_max_filesize alone does not work because post_max_size caps the whole request, and WordPress takes the smaller value.
PHP's manual for core php.ini directives says that when post data is larger than post_max_size, the $_POST and $_FILES arrays are empty. The upload then fails without a clear error, or WordPress still prints the old limit, because the request never reached it in a usable form.
A common case is a site with upload_max_filesize set to 64M and post_max_size still at the 8M default. The Media Library still shows 8 MB, because wp_max_upload_size returns the minimum of the two values.
The fix is to set post_max_size a few megabytes above upload_max_filesize, so the file plus the form fields and the request wrapper all fit.
A matching memory_limit matters too. The guide to fix “Allowed Memory Size Exhausted” explains that separate limit.
PHP's manual says memory_limit should be larger than post_max_size, so a site that raises the file limit to 64M while memory_limit sits at 128M is fine, but a site that raises it to 256M on a 128M memory limit can fail during image processing.
How can the web server block an upload before PHP sees it?
The web server can block an upload when its own body size limit is smaller than the file.
Nginx has a client_max_body_size directive, and its core module documentation says the default is 1m. When a request body is larger than the configured value, Nginx returns a 413 error to the client, so the upload never reaches PHP or WordPress at all.
The sign is a 413 error instead of the WordPress message. A file that fails with a 413 on Nginx, or a similar server error on Apache, points at the server setting, not at the PHP values. Raising the PHP limits changes nothing until the server limit rises too.
Apache has no direct equivalent in its core settings, but a host can still cap uploads through its own configuration or through a security module.
When the server limit is the cause, only the host or the server administrator can raise it. The guide to fix the HTTP error when uploading images covers upload failures that show a different message.
How can a host cap stop the limit from rising?
A host cap stops the limit from rising when the provider sets a maximum that no site setting can pass.
Many shared hosts cap upload_max_filesize at a fixed value, such as 16M or 64M, in the server configuration. Editing php.ini, .user.ini, or .htaccess below that cap works, but any value above it is ignored, and the Media Library keeps showing the capped number.
A plugin that raises the limit cannot pass a hard server cap either. Plugins that change the upload size work through the same PHP values, so they hit the same ceiling. The only way past a hard cap is a plan change or a host that allows a higher limit.
Check the current limit first in Tools, then Site Health, then Info, or on the Media Library upload screen, which prints the maximum upload file size.
If the number does not move after a correct edit and a PHP restart, the host cap is the likely cause, and the next step is to ask the host what the cap is. The guide on how to tell if your host is slowing WordPress down explains which host-side numbers to ask for.
How can the wrong php.ini file cause the error?
The wrong php.ini file causes the error when you edit one PHP setup while the site runs on another.
A server can have separate php.ini files for the command line and for the web server, and PHP-FPM pools can override php.ini values of their own. Editing the command line file changes what WP-CLI sees, while the site keeps using the web file, so the Media Library number never moves.
The check is to compare the value in Site Health with the value in the file you edited. Site Health shows the values the web server actually uses, so if it still shows the old limit, the edit went to the wrong file or the PHP service was not restarted after the edit.
PHP-FPM needs a restart or reload after a php.ini edit, and .user.ini files can take a few minutes to be picked up because PHP caches them.
A correct edit that shows no change is usually a restart problem, a cache problem, or the wrong file, not a WordPress problem. Developer.WordPress.org's Debugging in WordPress page notes that WP_DEBUG and the other debug tools are meant for local testing and staging, so use a staging copy when checking server settings.
How can a multisite network cap uploads?
A multisite network can cap uploads when the network settings set a maximum file size for every site in the network.
On a single site, WordPress does not add its own limit: wp_max_upload_size reports the PHP values, and nothing else.
On a multisite network, the Network Admin settings include a maximum upload file size that applies on top of the PHP values, so a network set to 10 MB caps every site at 10 MB even when PHP allows 64M.
The check is to open Network Admin, then Settings, and look at the upload size value there. If it is lower than the PHP limit, it is the ceiling, and only a network administrator can raise it.
This cause only applies to multisite networks, so a single site that shows the error does not have it. When a single site fails, the cause is one of the PHP values, the server limit, or the host cap instead.
What mistakes should you avoid?
Do not raise the limit to a huge number just because you can.
A very high limit lets large files eat disk space, backup space, and bandwidth, and it lets a bad upload tie up a PHP worker for a long time. Set the limit to the largest file the site genuinely needs, plus a small margin, and no higher.
Do not paste @ini_set lines for upload_max_size into wp-config.php and expect them to work. The setting name is upload_max_filesize, not upload_max_size, and PHP reads these values before WordPress runs, so a runtime change often has no effect. Edit php.ini, .user.ini, or the hosting panel instead.
Do not forget to restart PHP after editing php.ini. Saving the file without a restart changes nothing, and it is the most common reason a correct edit appears to have no effect. Check the Media Library number after the restart to confirm the new limit is live.
Frequently asked questions
Why does the upload limit stay the same after I raised upload_max_filesize?
WordPress reads the PHP values through wp_max_upload_size, which returns the smaller of upload_max_filesize and post_max_size. Raising only upload_max_filesize leaves post_max_size as the ceiling, so the Media Library number does not move. Set post_max_size a few megabytes above upload_max_filesize, and check that memory_limit is larger than post_max_size.
Does WordPress itself set an upload limit?
Yes, on a multisite network the Network Admin settings include a maximum upload file size that caps every site in the network. On a single site there is no WordPress-side limit, and the number comes only from PHP. Check Network Admin, then Settings, when a multisite upload is capped below the PHP limit.
What is the difference between the upload_max_filesize error and a 413 error?
A 413 error means the web server rejected the request before PHP saw it, usually because of a server body size limit such as Nginx client_max_body_size, which defaults to 1m. The WordPress message means PHP saw the file and refused it for passing upload_max_filesize. The two errors have different causes and different fixes.
How do I check my current upload limit?
Check the limit in Tools, then Site Health, then Info, or on the Media Library upload screen. The number shown is the limit the site actually uses. If it does not change after an edit, the edit may have gone to the wrong php.ini file, PHP may not have restarted, or the host may cap the value.
Can a plugin raise the upload limit past my host's cap?
A plugin can raise the limit only as far as the server allows, and it cannot pass a hard host cap or a server body size limit. A plugin is a convenient way to change the PHP values on a host that allows it, but the same result comes from editing php.ini or the hosting panel, and neither route works past a cap the host sets.
Sources
- wp_max_upload_size WordPress Developer Resources
- Description of core php.ini directives PHP Manual
- Module ngx_http_core_module Nginx
- Common WordPress Errors WordPress.org
- Debugging in WordPress WordPress Developer Resources
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
