expressjs/multer · error · TypeError

Expected object for argument options

Error message

Expected object for argument options

What it means

Thrown by multer's factory function `multer(options)` in index.js:101 when the `options` argument is neither `undefined` nor a plain non-null object. Multer uses this guard at the public API boundary because the constructor (index.js:11) immediately reads `options.storage`, `options.dest`, `options.limits`, etc. without any further type checking, so a non-object value would otherwise produce a confusing `TypeError: Cannot read properties of undefined/null` deep inside initialization. It is a fail-fast assertion that converts a class of late runtime crashes into an explicit, attributable error.

Source

Thrown at index.js:101

      storage: this.storage,
      fileFilter: this.fileFilter,
      fileStrategy: 'ARRAY'
    }
  }

  return makeMiddleware(setup.bind(this))
}

function multer (options) {
  if (options === undefined) {
    return new Multer({})
  }

  if (typeof options === 'object' && options !== null) {
    return new Multer(options)
  }

  throw new TypeError('Expected object for argument options')
}

module.exports = multer
module.exports.diskStorage = diskStorage
module.exports.memoryStorage = memoryStorage
module.exports.MulterError = MulterError

View on GitHub (pinned to 2e2af08157)

Solutions

1. Pass a plain object: replace `multer(null)` / `multer('uploads/')` with `multer({ dest: 'uploads/' })` or simply `multer({})`.
2. If the argument is optional or read from config, default it to an empty object: `multer(options || {})` rather than `multer(options || null)`.
3. If loading config from JSON/env, coerce and validate before calling multer: parse the JSON and assert the result is a non-null object before passing.
4. Add a unit test that calls your configuration helper to ensure it never returns a non-object to multer.

Example fix

// before
const upload = multer('uploads/')   // throws: string is not an object
// or
const upload = multer(opts ?? null)   // throws when opts is null

// after
const upload = multer({ dest: 'uploads/' })
// or, for optional config
const upload = multer(opts ?? {})

const multer = require('multer')

function makeUploader(options) {
  if (options === undefined || options === null) {
    return multer({})
  }
  if (typeof options !== 'object' || Array.isArray(options)) {
    throw new TypeError('multer options must be a plain object, got ' + typeof options)
  }
  return multer(options)
}

// Plain-object guard (multer accepts any non-null object, including class instances)
function isMulterOptions(value) {
  return typeof value === 'object' && value !== null && !Array.isArray(value)
}

let upload
try {
  upload = multer(maybeBadConfig)
} catch (err) {
  if (err instanceof TypeError && /Expected object for argument options/.test(err.message)) {
    throw new Error('Invalid upload configuration: multer expects a plain options object')
  }
  throw err
}

When it happens

Trigger: Calling `multer(null)` (null is explicitly rejected by the `options !== null` check at index.js:97), `multer('uploads/')` (string passed instead of `{ dest: 'uploads/' }`), `multer(42)`, `multer(true)`, or `multer([...])` (array). Note that `multer()` with no argument is allowed (index.js:93-95 returns `new Multer({})`), and any truthy/falsy plain object passes — only primitives, null, and non-object references trigger the throw.

Common situations: Most commonly a config refactor where a developer previously wrote `multer({ dest: 'uploads/' })` and accidentally simplified it to `multer('uploads/')`, or destructured wrong and passed `multer(dest)` instead of `multer({ dest })`. Also seen when reading config from an environment variable or JSON file and passing the raw string/number directly, or when null-coalescing logic produces `null` (e.g. `multer(options || null)`) instead of `multer(options || {})`.

Related errors

• Unknown file strategy:

AI-assisted analysis of expressjs/multer@2e2af08157 (2026-08-03). Data as JSON: /data/errors/52406ea2c0ec997c.json. Report an issue: GitHub.