AWS Lambda Multipart Form Data Parser

Common errors

• 502 Error: Bad Gateway

  cause API Gateway is not configured for Lambda Proxy Integration, or `integration: LAMBDA` is missing in Serverless Framework configuration.
  fix In API Gateway console, for your POST method's 'Integration Request', check 'Use Lambda Proxy Integration'. If using Serverless Framework, add `integration: LAMBDA` to your function's HTTP event configuration.

• Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause Your Lambda function's response is missing the `Access-Control-Allow-Origin` header required for cross-origin requests.
  fix Include `headers: { "Access-Control-Allow-Origin": "*" }` (or your specific frontend origin) in your Lambda function's response object.

Warnings

• breaking This library is effectively abandoned, with no updates or commits in over six years. It may not be compatible with newer Node.js runtimes (e.g., Node.js 18+), latest AWS Lambda features, or API Gateway configurations. Modern alternatives should be preferred.
  Fix: Consider using newer, actively maintained libraries like `busboy` or implementing custom parsing logic with current Node.js APIs, or leveraging API Gateway's direct integration features for file uploads if applicable.
• gotcha When integrating with API Gateway, it is crucial to set `integration: LAMBDA` in your `serverless.yml` or enable 'Use Lambda Proxy Integration' in the API Gateway console. Failing to do so will result in '502 Bad Gateway' errors.
  Fix: Ensure your API Gateway method's 'Integration Request' for your Lambda function has 'Use Lambda Proxy Integration' checked, or set `integration: LAMBDA` if using Serverless Framework.
• gotcha Default API Gateway CORS configurations do not always work correctly with `LAMBDA` integration for `multipart/form-data`. You must manually include `Access-Control-Allow-Origin` headers in your Lambda function's response.
  Fix: Add `"Access-Control-Allow-Origin": "*"` (or specific origin) to the `headers` object of your Lambda's response.
• gotcha The library returns file contents as Node.js `Buffer` objects by default for non-text files. If `spotText` is `true`, text files are returned as strings. Handling binary buffers correctly (e.g., converting to base64 for JSON responses) is crucial.
  Fix: When returning file content in a JSON response, convert `Buffer` objects to a base64 string (e.g., `file.content.toString('base64')`). Ensure the client knows how to decode it.

Install

• npm install aws-lambda-multipart-parser npm
• yarn add aws-lambda-multipart-parser yarn
• pnpm add aws-lambda-multipart-parser pnpm

Imports

• parse
  wrong:

  import parse from 'aws-lambda-multipart-parser';

  correct:

  const parse = require('aws-lambda-multipart-parser');

  The library is CommonJS-only and does not natively support ESM import syntax.
• parse
  wrong:

  import { parse } from 'aws-lambda-multipart-parser';

  correct:

  const { parse } = require('aws-lambda-multipart-parser');

  While `parse` is the primary export, destructuring from `require` is common. ESM named imports are not supported.

Quickstart

Demonstrates parsing an AWS Lambda event containing multipart/form-data and returning a structured JSON response, including necessary CORS headers.

const multipart = require('aws-lambda-multipart-parser');

exports.handler = (event, context, callback) => {
    // Ensure API Gateway is configured for binary media types and Lambda Proxy Integration.
    // The 'spotText' parameter can be set to true to have text files returned as strings.
    const parsedBody = multipart.parse(event, true);

    // Example of accessing a field and a file
    console.log('Form field value:', parsedBody.field);
    if (parsedBody.file) {
        console.log('File:', parsedBody.file.filename, parsedBody.file.contentType);
        // If spotText is true, content of text files is a string
        console.log('File content (text):', parsedBody.file.content);
    }

    const response = {
        statusCode: 200,
        headers: {
            "Access-Control-Allow-Origin": "*", // Essential for CORS if frontend is different origin
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            message: "Successfully parsed multipart data",
            data: parsedBody // Be careful exposing raw parsed data, especially buffers
        })
    };

    callback(null, response);
};