What Is File Upload Handling? How AI Builds Upload Features (And What Can Go Wrong)

Why AI Coders Need to Understand This

File uploads feel like a solved problem. You ask your AI to add a profile photo upload, it generates forty lines of code, and it works in your local dev environment. You ship. Three days later:

• All uploaded files have vanished from production.
• Or someone uploaded a file called ../../server.js and overwrote your app.
• Or your server crashed because someone uploaded a 2 GB video through your "image" uploader.

These are not hypotheticals — they are the three most common ways AI-generated file upload code fails. Understanding what the code actually does lets you catch these problems before they happen.

File upload handling touches more moving parts than almost any other feature: the browser's HTTP request format, middleware, Express route handling, cloud storage APIs, authentication, and security. Knowing the shape of the whole system means you can ask smarter questions and spot the gaps in AI output.

What Is multipart/form-data?

When a browser sends a regular form — username, password, email — it sends text. The HTTP request body looks like: username=alice&password=hunter2. Simple.

Files are different. A file is binary data — bytes, not text — and it can be huge. Browsers cannot just shove a file into a query string. So they use a different encoding called multipart/form-data.

Here is the idea: the browser splits the request body into multiple "parts," each separated by a unique boundary string. One part carries the regular form fields (the text). Other parts carry the file data, along with metadata like the original filename and content type.

-- boundary123
Content-Disposition: form-data; name="username"

alice
-- boundary123
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

[binary file data here]
-- boundary123--

Your server cannot read this the same way it reads regular JSON bodies. It needs a parser that understands this boundary-separated format. On the frontend, you tell the browser to use this encoding by using a FormData object or by setting enctype="multipart/form-data" on your HTML form.

// Frontend: sending a file with fetch
const formData = new FormData();
formData.append('avatar', fileInput.files[0]);
formData.append('username', 'alice');

// Do NOT set Content-Type manually — the browser sets it
// automatically with the correct boundary string
const response = await fetch('/api/upload', {
  method: 'POST',
  body: formData,
});

Notice: no Content-Type header. This is a common AI mistake — if you set Content-Type: multipart/form-data manually, you break it, because the browser needs to add the boundary parameter automatically.

Multer: The Middleware AI Always Reaches For

On the Express side, parsing multipart/form-data is not built in. That is where multer comes in — it is a middleware that reads incoming multipart requests and makes the file available at req.file (single file) or req.files (multiple files).

When you ask AI to add file uploads to an Express app, this is roughly what it generates:

const express = require('express');
const multer = require('multer');

const app = express();

// Configure where and how to store files
const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, 'uploads/'); // Folder to save files
  },
  filename: function (req, file, cb) {
    // WARNING: using original filename is a security risk
    // (see security section below)
    cb(null, file.originalname);
  }
});

const upload = multer({ storage });

// Single file upload: field name must match the FormData key
app.post('/api/upload', upload.single('avatar'), (req, res) => {
  console.log(req.file); // The uploaded file info
  res.json({ message: 'Upload successful', file: req.file });
});

The upload.single('avatar') call is multer acting as middleware. It runs before your route handler, parses the incoming multipart body, saves the file to disk, and attaches metadata to req.file. Your route handler then just reads that object.

Add file upload to my Express app. Use multer with
diskStorage. Validate that the file is an image (jpg,
png, webp only) and reject anything over 5MB. Generate
a random UUID filename instead of using the original.
Explain each part of the config.

Local Storage vs Cloud Storage: Why This Choice Matters

The multer example above saves files to the uploads/ folder on your server's disk. For local development, that is fine. For production, it is a disaster waiting to happen.

Most modern hosting platforms — Heroku, Railway, Render, Fly.io, Vercel functions — use ephemeral storage. The filesystem is temporary. Every time your app restarts, redeploys, or scales to a new instance, the disk is wiped clean. All your uploaded files are gone.

The standard production pattern is: multer stores the file temporarily in memory (multer.memoryStorage()), your route handler immediately uploads it to S3 or R2 using the AWS SDK, then discards it. The file never actually lives on your server's disk.

const multer = require('multer');
const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const { v4: uuidv4 } = require('uuid');
const path = require('path');

const s3 = new S3Client({ region: process.env.AWS_REGION });
const upload = multer({ storage: multer.memoryStorage() });

app.post('/api/upload', upload.single('avatar'), async (req, res) => {
  const ext = path.extname(req.file.originalname).toLowerCase();
  const key = `avatars/${uuidv4()}${ext}`; // Random filename

  await s3.send(new PutObjectCommand({
    Bucket: process.env.S3_BUCKET_NAME,
    Key: key,
    Body: req.file.buffer,
    ContentType: req.file.mimetype,
  }));

  const fileUrl = `https://${process.env.S3_BUCKET_NAME}.s3.amazonaws.com/${key}`;
  res.json({ url: fileUrl });
});

Note the environment variables — process.env.AWS_REGION, process.env.S3_BUCKET_NAME. Your AWS credentials and bucket name should never be hardcoded in source code.

Presigned URLs: Uploading Without Hitting Your Server

The pattern above works, but the file still passes through your server — browser uploads to Express, Express uploads to S3. For large files, this doubles the bandwidth and adds latency.

A better pattern for most production apps: presigned URLs. Your server generates a temporary URL that authorizes the browser to upload directly to S3, bypassing your server entirely.

const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
const { v4: uuidv4 } = require('uuid');

const s3 = new S3Client({ region: process.env.AWS_REGION });

// Step 1: Server generates presigned URL
app.post('/api/upload-url', async (req, res) => {
  const { fileType } = req.body; // e.g. "image/jpeg"
  const key = `uploads/${uuidv4()}.jpg`;

  const command = new PutObjectCommand({
    Bucket: process.env.S3_BUCKET_NAME,
    Key: key,
    ContentType: fileType,
  });

  // URL expires in 5 minutes
  const uploadUrl = await getSignedUrl(s3, command, { expiresIn: 300 });

  res.json({ uploadUrl, key });
});

// Browser then does:
// fetch(uploadUrl, { method: 'PUT', body: file, headers: { 'Content-Type': fileType } })
// Then calls your API with the key to save to the database

Generate a presigned URL flow for uploading profile photos
to S3. The backend should:
1. Validate the user is logged in before generating the URL
2. Only allow image/jpeg, image/png, image/webp
3. Set a 5-minute expiry
4. Return both the upload URL and the final public URL
Show frontend code too.

File Validation: What AI Often Skips

AI-generated upload code frequently skips or weakens file validation. This is not a minor omission — it is the difference between a functional app and a compromised one. Two things to always validate:

1. File Type Validation

There are two ways to check file type, and you want both:

const multer = require('multer');
const path = require('path');

const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
const ALLOWED_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.webp'];

const upload = multer({
  storage: multer.memoryStorage(),
  fileFilter: (req, file, cb) => {
    const ext = path.extname(file.originalname).toLowerCase();
    const mimeOk = ALLOWED_TYPES.includes(file.mimetype);
    const extOk = ALLOWED_EXTENSIONS.includes(ext);

    if (mimeOk && extOk) {
      cb(null, true); // Accept file
    } else {
      cb(new Error('Only JPEG, PNG, and WebP images are allowed'));
    }
  },
});

Checking both MIME type and extension matters because MIME type comes from the browser — and browsers trust the file extension. A user can rename script.php to photo.jpg and the browser will send image/jpeg. Checking the extension too catches this.

For higher security, use a library like file-type that reads the file's magic bytes (the actual binary signature at the start of the file) rather than trusting the declared MIME type at all.

2. File Size Validation

// Set size limit in multer config — 5MB
const upload = multer({
  storage: multer.memoryStorage(),
  limits: {
    fileSize: 5 * 1024 * 1024, // 5MB in bytes
  },
  fileFilter: /* ... */,
});

// Handle the multer size error in your error handler
app.use((err, req, res, next) => {
  if (err.code === 'LIMIT_FILE_SIZE') {
    return res.status(400).json({ error: 'File too large. Maximum size is 5MB.' });
  }
  next(err);
});

Without a size limit, anyone can upload a 10 GB file and crash your server or run up your S3 bill. Multer's limits.fileSize stops the upload as soon as the size is exceeded — it does not wait to receive the whole file.

Make sure your error handling middleware catches the multer error and returns a useful message instead of a raw 500.

Security Risks in File Uploads

File uploads are one of the highest-risk surfaces in any web app. Here are the three attacks that most commonly slip through AI-generated code:

Path Traversal Attacks

If your code uses the original filename to save the file:

// DANGEROUS — never do this
filename: (req, file, cb) => {
  cb(null, file.originalname); // User controls this string!
}

An attacker can upload a file named ../../config/database.js and potentially overwrite files anywhere on your server's filesystem. The fix is simple: never use the original filename. Generate a random UUID for every uploaded file:

const { v4: uuidv4 } = require('uuid');
const path = require('path');

filename: (req, file, cb) => {
  const ext = path.extname(file.originalname).toLowerCase();
  cb(null, `${uuidv4()}${ext}`); // Random name, validated extension only
}

Executable File Uploads

If someone uploads a .php, .js, or .sh file to a folder that your web server serves, and then requests that URL — the server might execute it. Your allowlist of accepted file types prevents this, but only if you actually enforce it on the server side. Client-side validation (checking in the browser) is easily bypassed. Server-side validation in multer is the real guard.

Malicious File Content

An image file can contain embedded malicious code in its metadata (EXIF data). This does not execute by itself, but can be used in cross-site scripting attacks if you ever display the raw EXIF data. For profile images and user-generated content, strip EXIF data using a library like sharp before storing:

const sharp = require('sharp');

// After multer puts file in memory, process it with sharp
app.post('/api/upload', upload.single('avatar'), async (req, res) => {
  // Re-encode the image — this strips EXIF and metadata
  const processedBuffer = await sharp(req.file.buffer)
    .resize(512, 512, { fit: 'cover' })
    .jpeg({ quality: 85 })
    .toBuffer();

  // Now upload processedBuffer to S3 instead of req.file.buffer
});

Common Errors and What They Mean

"MulterError: Unexpected field"

The field name in your FormData does not match what multer expects. If your route uses upload.single('avatar') but your frontend sends the file as formData.append('photo', file), multer rejects it with this error. Check that the field names match exactly.

// Backend expects:
upload.single('avatar')

// Frontend must send:
formData.append('avatar', file); // Must match!
// NOT:
formData.append('photo', file); // Mismatch = MulterError

"LIMIT_FILE_SIZE" / 413 Payload Too Large

The file exceeded your multer size limit. Also check your web server or proxy (nginx) — it may have its own body size limit that rejects the request before multer even sees it. With nginx, add client_max_body_size 10M; to your config.

Files disappear in production

You are saving to local disk on an ephemeral filesystem. Switch to S3 or R2 for production. Use environment variables to switch storage backend based on NODE_ENV.

S3 "Access Denied" on upload

Your AWS IAM user or role does not have s3:PutObject permission on the target bucket. Check your IAM policy. For presigned URLs, the credentials used to generate the URL must have upload permission on that specific bucket and key prefix.

CORS error when uploading to S3 directly

For presigned URL uploads (browser-to-S3 directly), you need to configure a CORS policy on your S3 bucket allowing PUT requests from your frontend's origin. This is separate from your Express CORS config. Add it in the AWS S3 console under Permissions → CORS configuration.

I'm getting [error message] when uploading files.
Here's my multer config and upload route:

[paste your code]

The upload works locally but fails in production on
[platform name]. What's wrong?

Real Scenarios Where AI Generates This Code

Here are the actual prompts that trigger file upload code generation — and what to watch for in each case:

Profile Photo Upload

"Add a profile photo upload to my user settings page." AI will generate multer + disk storage (change to memory + S3), and probably forget to resize the image or strip EXIF. Ask it to also add sharp for image processing and UUIDs for filenames.

Document Attachment

"Let users attach PDFs to their project." AI will generate multer accepting any file type — make sure the fileFilter is restricted to PDFs only. Also specify a size limit (PDFs can be large, 20–50MB may be appropriate) and ensure you are storing to S3, not disk.

CSV Import

"Add a CSV import feature." Here you actually do want multer.memoryStorage() because you are not storing the file at all — you parse it in memory and insert the rows into your database. AI often generates disk storage by default. Clarify in your prompt that the file should be parsed in memory and discarded.

Bulk Photo Upload

"Let users upload multiple photos at once." Use upload.array('photos', 10) instead of upload.single(). The second argument is the maximum number of files allowed. Always set this limit — without it there is no cap on concurrent uploads.

Add an image upload endpoint to my Express app.
Requirements:
- Use multer with memoryStorage (not disk)
- Accept only jpeg, png, and webp under 8MB
- Generate a UUID filename (never use original filename)
- Upload to S3 using @aws-sdk/client-s3
- Use environment variables for bucket name and region
- Add proper error handling for multer errors and S3 errors
- Require authentication using my existing auth middleware
- Return the public S3 URL on success

What to Learn Next

File uploads connect to several other backend topics. Understanding these makes the whole picture clearer:

• What Is Middleware? — multer is middleware. Understanding how middleware chains work explains why upload.single('avatar') can sit before your route handler.
• What Is Express? — the framework where most Node.js file upload code lives.
• What Is a REST API? — upload endpoints follow REST conventions. Understanding how REST routes work helps you structure upload APIs correctly.
• What Is Authentication? — uploads should always require authentication. Unauthenticated upload endpoints get abused immediately.
• What Is Error Handling? — multer throws specific errors that your error handler needs to catch and translate into useful responses.
• What Is an Environment Variable? — your S3 credentials, bucket names, and region must come from environment variables, never hardcoded.
• Security Basics for AI Coders — the full security picture for apps built with AI assistance.

FAQ