File Upload in Spring Boot: MultipartFile, S3, Streaming & Validation

At 2 AM your on-call phone rings. The service is throwing java.lang.OutOfMemoryError on every request. The root cause: a junior dev used file.getBytes() on a 500 MB video upload, loading the entire file into the JVM heap on every concurrent request. The pod crashed, and the autoscaler couldn't keep up. This is the most common file-upload mistake in Spring Boot, and it's entirely preventable.

File upload sounds simple — it's just bytes going from a browser to a server — but the production surface area is enormous. You need to think about request size limits at four layers: the client, the reverse proxy (Nginx/ALB), the Spring DispatchedServlet, and your application code. Missing any one layer causes mysterious 413 errors or silent truncation.

Multipart handling in Spring Boot changed significantly between Spring Boot 2 and 3. The underlying Tomcat, Jetty, or Undertow behaviour differs, and when you put a Kubernetes ingress in front, default body size limits of 1 MB will silently break uploads before your code even runs.

Then there's security. Accepting arbitrary files from the internet is an attack surface. Path traversal, polyglot files (a valid image that is also a ZIP bomb or a script), MIME type spoofing — each has a real CVE attached. Production file upload code must validate at the byte level, not at the filename level.

This guide covers everything from the basic MultipartFile handler through streaming with InputStream, virus scanning hooks, S3 multipart upload using AWS SDK v2, and the exact Actuator metrics you should alert on in production.

Basic MultipartFile Upload Endpoint

The simplest Spring Boot file upload endpoint uses @RequestParam MultipartFile file on a @PostMapping. This works for files that fit comfortably in memory — anything under ~50 MB on a well-tuned JVM. The critical first step is configuration: without explicit size limits, Spring Boot defaults to 1 MB for both max-file-size and max-request-size, which is useless for any real application.

Annotate your controller with @RestController and @RequestMapping. The MultipartFile parameter gives you access to getOriginalFilename(), getContentType(), getSize(), and getInputStream(). Never trust getOriginalFilename() or getContentType() — both come directly from the client and can be spoofed. A file named photo.jpg with Content-Type: image/jpeg can contain arbitrary bytes.

For small files, after validation, you can write to local disk with Files.copy(file.getInputStream(), destination, StandardCopyOption.REPLACE_EXISTING). For production systems, local disk is an antipattern — your pods are ephemeral. Write to S3, GCS, or Azure Blob Storage instead.

Always return a structured response — include the generated file ID (UUID), the storage path, the file size, and the detected MIME type. Never return the original filename in the response without sanitizing it, as it could contain path traversal sequences.

Streaming Large Files to S3 with AWS SDK v2

For files over 50 MB, or when running at scale, streaming directly to S3 without intermediate buffering is the only production-viable approach. AWS SDK v2 introduced S3AsyncClient and AsyncRequestBody.fromInputStream(), which pipes the MultipartFile's InputStream directly to S3 over HTTP/2 without ever materializing the bytes on the JVM heap.

For files over 100 MB, use the S3TransferManager (built on top of S3AsyncClient) which automatically splits the upload into 8 MB chunks and uploads them in parallel via the S3 multipart upload API. This is dramatically faster on high-bandwidth connections and is resumable — if the connection drops mid-upload, only the failed parts need to be retried.

The tricky part is that MultipartFile.getInputStream() can only be read once. If you need to compute a checksum or validate the file type in a streaming fashion, you must compose the stream: wrap it in a DigestInputStream for MD5/SHA-256, then pipe it through your validator, then to S3, all in a single read pass. Apache Tika supports streaming detection with AutoDetectParser.

For very large files (video, datasets), consider presigned S3 URLs: the client uploads directly to S3, bypassing your server entirely. Your server generates the presigned URL, the client uploads, and S3 triggers an event notification to your backend via SQS. This eliminates your server from the upload path entirely, which is the correct architecture for files over 500 MB.

Always set a content MD5 or SHA-256 header on S3 puts. S3 verifies the checksum and rejects corrupted uploads. This catches network corruption that would otherwise silently store a truncated file.

File Validation: Magic Bytes, Size Limits, and Virus Scanning

Production file upload validation has three layers: size limits (enforced at the framework level before your code runs), type validation (using magic bytes, not extensions), and content scanning (ClamAV or a commercial API for virus/malware detection).

Magic byte detection with Apache Tika is the standard approach. Tika reads the first few bytes of the stream and matches them against a database of known file type signatures. A JPEG always starts with FF D8 FF, a PNG with 89 50 4E 47, a PDF with 25 50 44 46. No amount of filename manipulation can fake these bytes.

For images, additionally validate that the file can actually be decoded as an image. Use ImageIO.read() wrapped in a try-catch — if it returns null or throws, the file is corrupt or a disguised binary. For a more thorough check, use the scrimage library which also detects image bombs (tiny files that expand to gigabytes when decoded).

Virus scanning in production typically uses ClamAV via its Unix socket. Run ClamAV as a sidecar in your Kubernetes pod and connect to its socket using the clamav4j library. Scan the input stream before storing it anywhere. For high-throughput systems, send files to a scanning queue asynchronously and move them from a quarantine bucket to the public bucket only after a clean scan result.

Path traversal prevention: never use file.getOriginalFilename() as a filesystem path. Always generate a UUID-based filename server-side. If you must preserve the original name for display, store it in a database field only — never use it for filesystem operations.

Global Exception Handling for Upload Errors

Upload error handling is a user experience problem as much as a technical one. By default, Spring Boot returns a 500 with a stack trace when MaxUploadSizeExceededException is thrown. Users see a cryptic error; the frontend has no structured error to parse. A @ControllerAdvice exception handler converts these to proper HTTP responses with machine-readable error bodies.

The key exceptions to handle: MaxUploadSizeExceededException (size limit hit), MissingServletRequestPartException (no file in the request), HttpMediaTypeNotSupportedException (wrong Content-Type header), MultipartException (any parsing failure), and your own custom StorageException and ValidationException.

For the 413 case, there's a subtlety: if the size limit is hit at the Tomcat level, the exception is thrown before your controller runs, so your @ControllerAdvice catches it. But if the limit is hit at the Nginx level, Nginx never forwards the request — your advice is never called. Document this distinction in your runbook.

Always include a trace-id (from MDC or Sleuth/Micrometer tracing) in error responses so that a user's support ticket can be correlated to a log line. Never include stack traces or internal paths in error responses.

Testing File Upload Endpoints

Testing file upload endpoints requires MockMultipartFile in unit tests and @SpringBootTest with TestRestTemplate or MockMvc for integration tests. The trap most developers fall into is testing only with small valid files — in production, the failures happen at the edges: empty files, files at exactly the size limit, files with spoofed MIME types, and concurrent uploads.

For integration tests, use MockMvc.perform(multipart(...)) to build the request. For testing size limit rejection, you need to mock a large MultipartFile — constructing an actual 100 MB file in a test is slow. Instead, mock MultipartFile.getSize() to return a large value and test the validation logic in isolation.

For S3 integration, use Testcontainers with the localstack image. LocalStack runs a real S3-compatible API locally. Wire your S3AsyncClient to point to http://localhost:4566 in the test profile. This tests the actual AWS SDK call, presigned URL generation, and multipart upload logic without hitting real AWS.

Always include a test that verifies the temp directory cleanup: after the upload completes (or fails), assert that no temp files remain in spring.servlet.multipart.location. Spring should clean them up, but custom code that stores the MultipartFile reference across thread boundaries can prevent cleanup and cause disk exhaustion.

Production Configuration and Observability

Complete production configuration requires tuning at four layers: Spring multipart, Tomcat connector, Kubernetes pod, and AWS infrastructure. Missing any layer creates a mismatch where upload succeeds in dev and fails silently in production.

For Tomcat, set server.tomcat.max-swallow-size=-1 to prevent Tomcat from aborting connections when the client sends more data than expected. Without this, clients uploading large files get a broken pipe even before Spring processes the request.

For observability, instrument every upload with Micrometer: a Timer for upload duration (segmented by file size bucket), a Counter for successes and failures, and a DistributionSummary for file sizes. Set alert thresholds: upload p99 > 30 seconds usually indicates an S3 or network issue; rejection rate > 5% usually indicates a bot attack or a broken client.

For the Kubernetes pod spec: set resources.limits.memory explicitly and run a load test to validate it before setting. If your upload handler is pure streaming, 512 MB per pod should handle dozens of concurrent 100 MB uploads. If anything calls getBytes(), memory is proportional to concurrent upload volume.

Finally, configure S3 bucket policies: block public access, enable versioning, enable server-side encryption with KMS, and set lifecycle rules to move objects to Glacier after 90 days. Enable S3 access logging to an audit bucket — this is required for compliance in most regulated industries.

MultipartResolver Gone? Why Spring Boot Just Works (Until It Doesn't)

The old-guard tutorials love configuring StandardServletMultipartResolver beans. Don't do it. Spring Boot 3.x auto-configures multipart handling the moment it sees spring.servlet.multipart.enabled=true (it defaults to true). The real trap? Your app works fine locally but fails in production with cryptic 'Required request part is missing' errors.

The why: Spring Boot wraps DispatcherServlet with a MultipartConfigElement automatically. But if you manually define a MultipartResolver bean or mess with servlet registrations, you override this auto-configuration. Then MultipartFile parameters become null because no resolver parses the request.

Production rule: Never define @Bean MultipartResolver. Never set multipartConfigElement on DispatcherServlet manually. Let Spring Boot handle it. If you need custom settings, use application.yml properties only. That single mistake took down our staging environment for three hours.

# io.thecodeforge — production config
spring:
  servlet:
    multipart:
      enabled: true          # auto-configured; explicit for clarity
      max-file-size: 10MB    # per-file limit
      max-request-size: 50MB # total request limit (multiple files)
      file-size-threshold: 2MB # size threshold for writing to disk vs memory
      location: /tmp/uploads # temp directory before processing

Upload Files With Form Data: The Bad Practice That Leaks Memory

Need to send a file alongside a user ID or description? The obvious approach—sending the form data as separate request parameters—works. Until you hit a 200MB file and realize you serialized a giant JSON payload into memory alongside it.

Better approach: Use @RequestPart instead of @RequestParam. Why? @RequestPart treats each part of the multipart request independently, streaming file content while the JSON part is deserialized separately. @RequestParam with MultipartFile forces the entire request body into memory first.

Here's the pattern: Declare a DTO for non-file fields, and annotate it with @RequestPart. The file stays as MultipartFile. Spring handles the deserialization and streaming separately. This prevents OutOfMemoryErrors when users upload 4K video files with metadata.

Memory tip: Combine this with spring.servlet.multipart.file-size-threshold set to 0 to force all files straight to disk. Production servers with 512MB RAM survived a 2GB upload stress test using this pattern.

// io.thecodeforge — java tutorial
@RestController
@RequestMapping("/api/uploads")
public class UploadController {

    @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<UploadResponse> uploadWithMetadata(
        @RequestPart("metadata") UploadMetadata metadata,  // JSON part
        @RequestPart("file") MultipartFile file) {           // file part

        String fileName = file.getOriginalFilename();
        long size = file.getSize();
        String userId = metadata.userId();

        // Streaming write to disk or S3 — never call file.getBytes()
        saveFileToStorage(file.getInputStream(), userId, fileName);

        return ResponseEntity.ok(new UploadResponse(fileName, size, userId));
    }

    record UploadMetadata(String userId, String description) {}
    record UploadResponse(String fileName, long size, String userId) {}
}