> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin and theme installation fails with "Upload failed"

> Plugin upload failures can be caused by PHP tmpfile() being disabled, security rules blocking connections, or localhost setups not accepting external traffic. Check server settings and security configurations.

The "Upload failed" error appears when MainWP cannot transfer plugin or theme files from your Dashboard to child sites. This is typically caused by server configuration, security settings, or localhost limitations.

## What You'll Learn

* Identify the cause of upload failures
* Check server configuration requirements
* Resolve security rule conflicts
* Understand localhost limitations

## Prerequisites

* MainWP Dashboard installed and activated
* Admin access to your Dashboard site
* Access to server configuration (or hosting support)

***

## Check Server Configuration

### PHP tmpfile() Function

The `tmpfile()` PHP function is required for processing file uploads. If disabled, uploads fail.

**1. Check Server Information**

Go to **MainWP > Info > Server** and look for disabled PHP functions.

**2. Contact hosting if needed**

If `tmpfile()` is disabled, contact your hosting provider to enable it.

### File Size Limits

Your server must allow uploads large enough for plugin and theme .zip files.

| Setting | Recommended Value | Where to Check |
| - | - | - |
| upload\_max\_filesize | 64M or higher | MainWP > Info > Server |
| post\_max\_size | 64M or higher | MainWP > Info > Server |
| max\_execution\_time | 300 seconds | MainWP > Info > Server |

If these values are too low, contact your hosting provider or modify php.ini.

***

## Check Security Rules

Security configurations can block the upload process. Try these steps in order.

### .htaccess Rules

**1. Review .htaccess**

Check the .htaccess file in your Dashboard's WordPress directory for security rules that might block uploads.

**2. Temporarily rename**

Rename .htaccess to .htaccess.backup to test if it's causing the issue.

**3. Test upload**

Attempt the plugin/theme upload again.

**4. Restore or modify**

If uploads work, restore .htaccess and adjust the specific rule causing the block.

### Security Plugins

Security plugins on your Dashboard can interfere with upload processes.

**1. Temporarily disable**

Deactivate security plugins on your Dashboard site (not child sites).

**2. Test upload**

Attempt the upload again.

**3. Identify conflict**

If successful, re-enable plugins one by one to find the conflicting one.

**4. Configure exception**

In the conflicting plugin, add an exception for MainWP operations.

### Server Firewall

Your hosting provider's firewall may block the connection.

* Contact hosting support to check firewall logs
* Request whitelisting for your Dashboard's internal processes
* Verify that ModSecurity or similar WAF isn't blocking uploads

### HTTP Basic Authentication

If your Dashboard is protected by HTTP Basic Auth (.htpasswd), uploads may fail.

**1. Temporarily disable**

Remove HTTP Basic Auth protection from your Dashboard URL.

**2. Test upload**

Attempt the upload.

**3. Re-enable if needed**

After confirming uploads work, consider alternative security measures that don't interfere with MainWP.

### Access Restrictions on the Dashboard Admin Area

When you install a plugin or theme from an uploaded .zip file, each child site downloads the file from your Dashboard through a signed link. By default, this link points to your Dashboard's `/wp-admin/` URL.

If `/wp-admin/` sits behind an access layer that child sites cannot pass, such as an identity-aware proxy (for example, Cloudflare Access) or an IP allowlist, the child site may receive a sign-in page or an HTTP error when it requests the ZIP file.

Starting with MainWP Dashboard 6.4.2, you can use the `mainwp_download_url` filter to move the download link to your Dashboard's front end. Keep the signed query string intact and use an HTTPS URL on the Dashboard site that your child sites can reach.

Add this code on the **MainWP Dashboard site**, for example in the PHP section of the [MainWP Custom Dashboard Add-on](https://docs.mainwp.com/add-ons/development/mainwp-custom-dashboard-extension.md) or a custom plugin:

```php theme={null}
add_filter( 'mainwp_download_url', 'mycustom_mainwp_download_url', 10, 2 );
function mycustom_mainwp_download_url( $url, $query ) {
    // Serve the signed download link from the front end instead of /wp-admin/.
    return home_url( '/' . $query, 'https' );
}
```

Retry the installation from MainWP and check the result for each child site.

***

## Localhost Limitations

If your MainWP Dashboard runs on a local development environment (localhost), child sites on remote servers cannot connect back to receive files.

### Why This Happens

* Localhost is not accessible from the internet
* Child sites cannot reach your local Dashboard to download files
* The upload process requires two-way communication

### Solutions for Localhost

| Option | Description |
| - | - |
| Use a tunnel | Tools like ngrok expose localhost to the internet temporarily |
| Upload directly | Install plugins/themes directly on child sites for testing |
| Use staging | Test with a publicly accessible staging Dashboard |

***

## Self-Check Checklist

* [ ] PHP tmpfile() function is enabled
* [ ] upload\_max\_filesize is adequate
* [ ] .htaccess doesn't block uploads
* [ ] Security plugins temporarily disabled for testing
* [ ] HTTP Basic Auth disabled (if applicable)
* [ ] Dashboard is publicly accessible (not localhost)
* [ ] Uploads complete successfully

***

## Related Resources

* [Resolve System Requirements](https://docs.mainwp.com/troubleshooting/resolve-system-requirement-issues.md) - Server configuration issues
* [Enable tmpfile on Cloudways](https://docs.mainwp.com/advanced/miscellaneous/enable-tmpfile-php-function-on-cloudways.md) - Cloudways-specific fix
* [Troubleshoot Connection Problems](https://docs.mainwp.com/troubleshooting/potential-issues.md) - General connection issues


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.