PHP File Upload Limit: upload_max_filesize, post_max_size, and Memory Limits

The PHP default upload_max_filesize is 2M (2 megabytes) across standard runtime installations, and post_max_size is 8M (8 megabytes). When an incoming file exceeds these thresholds, PHP drops the request payload silently, leaving both the $_POST and $_FILES superglobals completely empty without raising a default runtime exception.

The PHP file upload limit is a set of configuration directives in php.ini, primarily upload_max_filesize and post_max_size, that dictate the maximum byte size of files and HTTP POST requests that a PHP script will accept.

When a browser or API client transmits a file using an HTTP POST request with a Content-Type of multipart/form-data, the web server receives the byte stream and hands it to the PHP process. PHP processes the incoming multipart stream before executing any user-space script code. It extracts individual form boundaries, validates the payload against internal configuration directives, writes the incoming binary stream to a temporary directory on disk, and populates the $_FILES superglobal array with file metadata.

Understanding how PHP enforces these boundaries requires distinguishing between the two primary directives:

1. upload_max_filesize: Governs the maximum allowable size of a single uploaded file. If an individual file exceeds this threshold, PHP stops writing the file to disk and sets the error key in the $_FILES array to 1 (which maps to the UPLOAD_ERR_INI_SIZE constant). The script continues executing, and other smaller files or text fields in the same request remain available in $_POST and $_FILES.
2. post_max_size: Dictates the maximum byte size of the entire HTTP POST request body. This includes all uploaded files combined, plus text form inputs, hidden CSRF tokens, multipart boundary delimiters, and MIME headers. If the total request body exceeds post_max_size, PHP halts multipart parsing immediately.

This architectural difference creates a common operational trap. When an upload exceeds upload_max_filesize but remains under post_max_size, user scripts can catch the failure by inspecting $_FILES['document']['error']. However, when an upload exceeds post_max_size, PHP discards the entire POST payload. Both $_POST and $_FILES arrive as empty arrays. In frameworks such as Laravel or Symfony, this silent drop triggers form validation errors stating that required text fields are missing, masking the underlying upload size limit failure.

Furthermore, developers cannot resolve this issue by calling ini_set('upload_max_filesize', '50M') or ini_set('post_max_size', '64M') at runtime. In PHP, both directives have a configuration changemode of PHP_INI_PERDIR. They can be declared in php.ini, Apache .htaccess files, or PHP-FPM pool configurations, but cannot be modified using ini_set() inside application scripts. Because PHP parses multipart data before executing application code, runtime adjustments occur after the request body has already been evaluated or discarded.

The following table summarizes the core PHP configuration directives that govern file ingestion limits:

• FastAPI Upload File Size Limits: Memory Spooling, Middleware, and Direct StorageFastAPI imposes no native file size limit, but Starlette spools multipart uploads in memory up to `1,048,576 bytes`...
• Notion File Upload Limits: Size Caps by Plan and Large-File WorkaroundsNotion limits individual file uploads to 5MB on the Free plan and provides unlimited file uploads with a 5GB maximum...
• AWS Bedrock File Size Limits: Document Constraints in Knowledge Bases and Converse APIAWS Bedrock Knowledge Bases enforces a 50 MB per-document limit for file ingestion, while the Bedrock Converse API caps...
• AWS Lambda File Size Limits: Payload, Package, and Ephemeral Storage CapsAn AWS Lambda file size limit encompasses the execution constraints of AWS Lambda functions, specifically the 50MB...
• S3 Presigned URL File Size Limit: Upload Caps, Multipart Transfers & AlternativesThe Amazon S3 presigned URL file size limit is strictly 5 GB for a single HTTP PUT operation, governed by the PutObject...
• Airtable Attachment Limits: File Sizes, Base Storage, and WorkaroundsThe Airtable attachment limit framework caps individual file uploads at 5 GB across all subscription tiers, while...

More on this subject: Agent File and Document Workflows (298 guides)

Configuring PHP to accept larger file transfers requires updating four related directives simultaneously. Increasing upload_max_filesize in isolation will not work if the total POST size, available memory, or socket execution timers cut the request short.

To permit reliable uploads, your configuration must satisfy the following size hierarchy:

memory_limit > post_max_size > upload_max_filesize

Here is the operational checklist of the four directives that must be aligned in php.ini:

1. upload_max_filesize: Set this directive to the absolute maximum size you want to permit for any single file asset.
2. post_max_size: Set this directive higher than upload_max_filesize. Because an HTTP multipart request wraps binary data in MIME boundaries and transmits companion form fields, the total POST body is always larger than the file itself. A recommended operational pattern is setting post_max_size comfortably larger than upload_max_filesize (such as adding several additional megabytes of buffer space) for single-file forms. If your application allows users to upload multiple files simultaneously (governed by max_file_uploads), post_max_size must accommodate the combined sum of all files in the batch.
3. memory_limit: Ensure PHP has sufficient volatile RAM to handle the request. As documented in the official PHP manual, memory_limit should generally be larger than post_max_size. While PHP streams incoming multipart files directly to temporary disk storage rather than loading the entire file into RAM, subsequent script processing often reads the file into memory. Operations like generating image thumbnails, extracting text from PDFs, or hashing file contents allocate memory buffers proportional to the asset size.
4. max_execution_time and max_input_time: Network transfers take time. The max_input_time directive sets the maximum number of seconds PHP allows for receiving and parsing input data, including multipart file uploads. The max_execution_time directive governs how long the script is allowed to run once parsing completes. On a standard broadband uplink, uploading a 100 megabyte file might take 15 to 45 seconds; on slower mobile connections, it can take several minutes. If max_input_time is set to the default 60 seconds, slower connections will trigger an immediate timeout mid-upload.

The following configuration examples demonstrate recommended sizing targets for common operational tiers:

;; ====================================================================
;; Tier 1: Standard Document Uploads (up to 25 MB files)
;; ====================================================================
upload_max_filesize = 25M
post_max_size = 32M
memory_limit = 128M
max_execution_time = 120
max_input_time = 120

;; ====================================================================
;; Tier 2: Large Media and Archive Uploads (up to 100 MB files)
;; ====================================================================
upload_max_filesize = 100M
post_max_size = 125M
memory_limit = 256M
max_execution_time = 300
max_input_time = 300

;; ====================================================================
;; Tier 3: Heavy Dataset and Video Assets (up to 500 MB files)
;; ====================================================================
upload_max_filesize = 500M
post_max_size = 550M
memory_limit = 1024M
max_execution_time = 900
max_input_time = 900

When specifying memory and size directives in php.ini, PHP accepts shorthand byte notation: K for kilobytes, M for megabytes, and G for gigabytes. These suffixes are case-insensitive (100M and 100m are identical). If you specify a raw number without a suffix, PHP interprets the value in bytes.

Be cautious on older 32-bit PHP installations. In 32-bit environments, PHP stores sizes internally using signed 32-bit integers, which imposes a hard ceiling of 2,147,483,647 bytes (approximately 2 GB). Setting upload_max_filesize or post_max_size to 2048M or higher on a 32-bit build causes integer wrap-around, leading to unexpected negative values and failed uploads. Modern 64-bit PHP builds do not suffer from this restriction, but pushing gigabyte-scale files through standard HTTP POST bodies introduces severe server load regardless of integer capacity.

Locating the Active Configuration File

A frequent source of misconfiguration is editing a php.ini file that is not loaded by the active web runtime. Linux distributions maintain distinct configuration files for the Command Line Interface (CLI) and web process managers (PHP-FPM, Apache mod_php).

To find the configuration file used by your command line environment, run:

php --ini

This command outputs the path to the loaded configuration file, such as /etc/php/8.3/cli/php.ini. However, your web server almost certainly uses a different file, typically located at /etc/php/8.3/fpm/php.ini or /etc/php/8.3/apache2/php.ini.

To determine the exact php.ini file governing your web server, create a temporary diagnostic file in your web root named info.php:

<?php
phpinfo();

Open this file in your browser and locate the following two rows in the top configuration table:

• Loaded Configuration File: The absolute path to the primary php.ini parsed by the web process.
• Scan this dir for additional .ini files: Any directory containing modular configuration snippets that override the base file.

Always remove info.php immediately after checking your settings, as exposing system details presents a security risk.

Configuring php.ini is only half the battle. In modern web architectures, PHP runs behind an upstream reverse proxy or web server such as Nginx or Apache HTTP Server. These front-line web servers enforce their own request body limits. If an incoming file upload exceeds the web server's configured threshold, the proxy rejects the request immediately before PHP ever sees it.

Configuring Nginx client_max_body_size

Nginx acts as a reverse proxy in front of PHP-FPM. By default, Nginx enforces a strict client_max_body_size of 1m (1 megabyte). If an HTTP client uploads a 5 megabyte file to a server where php.ini allows 100 megabytes, Nginx terminates the connection and returns an HTTP 413 Request Entity Too Large error page. The request never reaches PHP-FPM, and PHP error logs show no entry.

The client_max_body_size directive can be placed within the http, server, or location block of your nginx.conf file:

• http block: Sets a global default limit across all hosted virtual domains.
• server block: Sets the limit for a specific domain name or virtual host.
• location block: Applies a larger upload limit strictly to specific file ingestion endpoints, keeping the rest of the application protected against oversized payloads.

The following configuration example demonstrates setting a 10 megabyte default across the domain while permitting 100 megabytes on a dedicated upload path:

server {
    listen 80;
    server_name app.example.com;
    root /var/www/app/public;
    index index.php;
    ###
    ### General request limit for the domain
    client_max_body_size 10M;
    ###
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    ###
    ### Dedicated upload route with elevated limits and extended timeouts
    location /api/v1/uploads {
        client_max_body_size 100M;
        ###
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        ###
        ### Prevent 504 Gateway Timeout during heavy file transfers
        fastcgi_read_timeout 300s;
        fastcgi_send_timeout 300s;
    }
    ###
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 60s;
    }
}

Notice the fastcgi_read_timeout setting. If a PHP script takes longer than Nginx's default 60-second read timeout to process, virus-scan, or move an uploaded asset, Nginx drops the client connection and outputs an HTTP 504 Gateway Timeout. Raising fastcgi_read_timeout to match your PHP max_execution_time prevents early connection drops.

Configuring Apache HTTP Server

Apache HTTP Server controls request body sizes using the LimitRequestBody directive. In Apache 2.4.54 and later versions, LimitRequestBody defaults to 1073741824 bytes (1 GiB). In older releases, it defaulted to 0 (unlimited).

The value is specified in bytes. You can configure LimitRequestBody within the main server configuration (apache2.conf or httpd.conf), inside a <VirtualHost> block, within a <Directory> block, or inside a local .htaccess file:

<VirtualHost *:80>
    ServerName app.example.com
    DocumentRoot /var/www/app/public
    ###
    ### Allow uploads up to 100 MB (104,857,600 bytes)
    LimitRequestBody 104857600
    ###
    <Directory "/var/www/app/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

When running PHP as an Apache module (mod_php), you can also configure PHP upload directives directly inside a local .htaccess file:

### Set upload directives via .htaccess on Apache mod_php
php_value upload_max_filesize 100M
php_value post_max_size 125M
php_value memory_limit 256M
php_value max_execution_time 300
php_value max_input_time 300

Overriding Settings in PHP-FPM Pool Files

If your infrastructure uses PHP-FPM, you can set directives per pool (for instance, in /etc/php/8.3/fpm/pool.d/www.conf) instead of modifying the global php.ini. This approach is useful for multi-tenant environments where one application requires larger upload quotas than others on the same host.

PHP-FPM provides two configuration prefixes:

• php_value: Sets a configuration directive that can still be overridden by downstream user scripts or per-directory .user.ini files.
• php_admin_value: Sets a locked configuration directive that downstream user scripts cannot alter under any circumstances.

Add the following directives to your pool configuration to enforce upload limits at the process pool boundary:

;; /etc/php/8.3/fpm/pool.d/www.conf
php_admin_value[upload_max_filesize] = 100M
php_admin_value[post_max_size] = 125M
php_admin_value[memory_limit] = 256M
php_admin_value[max_execution_time] = 300
php_admin_value[max_input_time] = 300

Applying Changes Safely

Configuration adjustments do not take effect until services reload their configuration files. Test syntax before reloading to avoid accidental downtime:

### Validate and reload Nginx
sudo nginx -t
sudo systemctl reload nginx

### Validate and reload PHP-FPM
sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpm

### Validate and reload Apache
sudo apachectl configtest
sudo systemctl reload apache2

Ingest and Query Large Corpora Beyond PHP Upload Ceilings

Store multi-gigabyte datasets in persistent workspaces with automatic hybrid search, per-file version history, and remote MCP access for AI agents. Monthly plans start with a 14-day free trial.

Start 14-Day Trial

When an upload fails, identifying whether the error originated in Nginx, Apache, the PHP multipart parser, or filesystem permissions prevents hours of blind trial-and-error.

Inspecting the $_FILES Error Code

Whenever PHP processes a file upload, it assigns an integer error code to the error key of the file array in $_FILES. Inspecting this value reveals the exact cause of the failure:

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (!isset($_FILES['attachment'])) {
        echo "No upload array found. Check post_max_size or form enctype.";
        exit;
    }
    ###
    $errorCode = $_FILES['attachment']['error'];
    switch ($errorCode) {
        case UPLOAD_ERR_OK:
            echo "File uploaded successfully.";
            break;
        case UPLOAD_ERR_INI_SIZE:
            echo "Error 1: File exceeds upload_max_filesize in php.ini.";
            break;
        case UPLOAD_ERR_FORM_SIZE:
            echo "Error 2: File exceeds MAX_FILE_SIZE specified in HTML form.";
            break;
        case UPLOAD_ERR_PARTIAL:
            echo "Error 3: File was only partially uploaded due to network interruption.";
            break;
        case UPLOAD_ERR_NO_FILE:
            echo "Error 4: No file was selected for upload.";
            break;
        case UPLOAD_ERR_NO_TMP_DIR:
            echo "Error 6: Missing temporary folder on server.";
            break;
        case UPLOAD_ERR_CANT_WRITE:
            echo "Error 7: Failed to write file to disk. Check permissions or disk space.";
            break;
        case UPLOAD_ERR_EXTENSION:
            echo "Error 8: A PHP extension stopped the file upload.";
            break;
        default:
            echo "Unknown upload error code: {$errorCode}";
            break;
    }
}

Catching the Empty $_POST and $_FILES Anomaly

The most frustrating failure mode occurs when a request exceeds post_max_size. Because PHP drops the entire payload, $_FILES['attachment']['error'] does not exist because $_FILES is completely empty.

You can reliably detect this condition by checking whether the request method is POST, the Content-Length header is greater than zero, and both input arrays are empty:

<?php
function check_for_post_max_size_overflow(): ?string {
    if ($_SERVER['REQUEST_METHOD'] === 'POST' && empty($_POST) && empty($_FILES)) {
        $contentLength = (int)($_SERVER['CONTENT_LENGTH'] ?? 0);
        if ($contentLength > 0) {
            $postMaxSize = ini_get('post_max_size');
            return "Upload failed: Incoming request of {$contentLength} bytes exceeded the post_max_size setting ({$postMaxSize}).";
        }
    }
    return null;
}

$error = check_for_post_max_size_overflow();
if ($error) {
    http_response_code(413);
    echo json_encode(['error' => $error]);
    exit;
}

Adding this check to your application's entry point or middleware layer transforms a mysterious silent validation failure into a clear, actionable diagnostic message.

Verifying Temporary Directory Permissions and Disk Space

When PHP receives an uploaded file, it writes the stream into a temporary directory specified by the upload_tmp_dir directive in php.ini. If this directive is not set, PHP defaults to the system temporary directory (typically /tmp on Linux systems).

Two common server-level problems cause upload failures at this stage:

1. Permission Denied (UPLOAD_ERR_CANT_WRITE): The user account running the PHP process (such as www-data or nginx) must have read and write permissions on the temporary folder. If permissions were altered, reset them using:

sudo chmod 1777 /tmp

2. Disk Capacity Exhaustion: If the partition holding /tmp reaches full capacity, PHP cannot write incoming files. Check disk allocation with df -h. In containerized environments like Docker or Kubernetes, /tmp is frequently mounted on a temporary RAM filesystem (tmpfs). Uploading a 200 megabyte file to a container provisioned with a 128 megabyte tmpfs volume will crash the write operation immediately.

While adjusting php.ini and web server directives allows PHP to ingest larger files, pushing multi-hundred-megabyte or gigabyte assets through standard synchronous HTTP POST requests introduces severe architectural trade-offs:

• Worker Thread Starvation: A PHP-FPM worker process remains locked and occupied for the entire duration of a client upload. If twenty users simultaneously upload 200 megabyte files over slow mobile connections, twenty PHP-FPM workers remain blocked for minutes simply waiting on socket I/O. This starves the server of available workers to serve regular, lightweight application requests.
• I/O and Disk Amplification: In standard PHP uploads, data is written to disk twice: first to /tmp as a temporary file, and second when your script calls move_uploaded_file() to transfer it into permanent storage or an object store.
• Lack of Resumability: If an upload fails near completion due to a network glitch, standard HTTP POST mechanisms require the client to restart transmission from byte zero.

For high-volume web applications, data ingestion pipelines, and AI agent workloads, modern engineering teams adopt decoupled architectural patterns:

Pattern 1: Direct-to-Storage Presigned URLs

Instead of streaming binary payloads through PHP application servers, clients upload files directly to cloud object storage (such as Amazon S3, Google Cloud Storage, or Cloudflare R2).

In this architecture:

1. The client requests a secure upload token from a lightweight PHP endpoint: POST /api/uploads/presign.
2. The PHP application verifies user authentication, checks authorization, and generates a short-lived presigned URL.
3. The client uploads the binary asset directly to the storage bucket using HTTP PUT.
4. Upon successful upload, the storage service triggers an asynchronous webhook or the client notifies the PHP API to register the completed file.

This pattern relieves PHP workers from handling binary socket streams entirely, reducing server RAM requirements and eliminating PHP timeout concerns.

Pattern 2: Client-Side Chunked Uploads

For applications requiring resumable uploads directly within the browser, chunked upload protocols (such as the Tus open protocol) break massive files into discrete 5 megabyte or 10 megabyte slices on the client side.

Each chunk travels as an independent HTTP POST or PATCH request. Because every individual slice remains well below default web server limits, the upload passes through Nginx and PHP without triggering 413 Request Entity Too Large errors or timeout thresholds. If the connection drops mid-transfer, the client resumes from the last acknowledged chunk rather than starting over.

Pattern 3: Decoupling Files into Persistent, Intelligent Workspaces

AI agents and automated data pipelines encounter a distinct challenge: once large files (such as legal discovery sets, financial ledgers, or product documentation binders) are collected, agents need to search, extract, and reason over that data without saturating model context windows or hitting HTTP payload limits.

Instead of passing massive files directly through chat prompts or fragile API uploads, teams store their documents in persistent, intelligent workspaces. Explore our architecture guides on storage for agents and AI storage for implementation details.

Fast.io provides shared workspaces designed for human and agent collaboration:

• Unified Ingestion: Workspaces ingest files via direct chunked upload, URL imports, or scheduled and on-demand Cloud Sync from existing cloud storage providers, including Google Drive, Dropbox, Box, and OneDrive (with SharePoint libraries supported through the OneDrive connector).
• Automatic Semantic Indexing: Enabling Intelligence Mode on a workspace automatically indexes files for hybrid search (combining full-text keyword search, semantic vector retrieval, and metadata queries). Files become queryable immediately without configuring separate vector databases or embedding pipelines.
• Remote Model Context Protocol (MCP) Tooling: Autonomous agents connect to Fast.io workspaces via the remote MCP server hosted over Streamable HTTP at https://mcp.fast.io/mcp/tools (for general assistants and personal runtimes) or https://mcp.fast.io/mcp/code (for coding agents). Agents query the workspace over MCP and retrieve precise, relevant document snippets accompanied by verifiable citations, bypassing PHP upload ceilings entirely.
• Per-File Version History: Every file modification creates a clear version history, making concurrent agent updates auditable and reversible.
• Detailed Activity Log: Organization and workspace activity logs record configuration and file modifications, providing operational visibility across human and agent actions.
• Ownership Transfer: AI agents can establish workspaces, ingest documentation corpora, configure shares, and transfer ownership to human administrators while maintaining assigned operational permissions.

Monthly plans start with a 14-day free trial that requires a credit card. Review our pricing plans for options: Starter at $9.99/mo (3 seats, 250 GB storage, 5 workspaces, 100,000 credits a month), Business at $49.99/mo (10 seats, 5 TB storage, 50 workspaces, 600,000 credits a month), and Enterprise at $199.99/mo (30 seats included, 25 TB storage, 200 workspaces, 3,000,000 credits a month). Maximum upload sizes are 25 GB on Starter, 50 GB on Business, and 100 GB on Enterprise. Credits meter AI operations, with overage billed at $10 per 100,000 credits.