transloadit/uppy · error · ValidationError

fieldname must be a string

Error message

fieldname must be a string

What it means

The optional fieldname option (the form field name used for multipart uploads) must be a string when provided. Passing any other type throws a ValidationError.

Source

Thrown at packages/@uppy/companion/src/server/Uploader.ts:127

  // validate HTTP Method (optional)
  if (options.httpMethod) {
    if (typeof options.httpMethod !== 'string') {
      throw new ValidationError('unsupported HTTP METHOD specified')
    }

    const method = options.httpMethod.toUpperCase()
    if (method !== 'PUT' && method !== 'POST') {
      throw new ValidationError('unsupported HTTP METHOD specified')
    }
  }

  if (exceedsMaxFileSize(options.companionOptions.maxFileSize, options.size)) {
    throw new ValidationError('maxFileSize exceeded')
  }

  // validate fieldname (optional)
  if (options.fieldname != null && typeof options.fieldname !== 'string') {
    throw new ValidationError('fieldname must be a string')
  }

  // validate metadata (optional)
  if (options.metadata != null && typeof options.metadata !== 'object') {
    throw new ValidationError('metadata must be an object')
  }

  // validate headers (optional)
  if (options.headers != null && typeof options.headers !== 'object') {
    throw new ValidationError('headers must be an object')
  }

  // validate protocol (optional)
  if (
    options.protocol &&
    !Object.values(PROTOCOLS).includes(options.protocol)
  ) {
    throw new ValidationError('unsupported protocol specified')

View on GitHub (pinned to 5d4dedd02a)

Solutions

  1. Pass fieldname as a string, e.g. 'file'
  2. Omit it or pass null to use the default
  3. Coerce with String(fieldname) when sourced from untyped input

Example fix

// before
fieldname: req.body.field

// after
fieldname: typeof req.body.field === 'string' ? req.body.field : undefined
Defensive patterns

Strategy: type-guard

Validate before calling

if (fieldname != null && typeof fieldname !== 'string') fieldname = String(fieldname)

Type guard

const isFieldname = (f: unknown): f is string => typeof f === 'string'

Try / catch

null

Prevention

When it happens

Trigger: new Uploader({ fieldname: 123 }) or fieldname: { name: 'file' } — any non-string, non-null value.

Common situations: fieldnames pulled from untyped multipart/form-data parsers or request bodies that arrive as non-strings.

Related errors

AI-assisted analysis of transloadit/uppy@5d4dedd02a (2026-08-28). Data as JSON: /api/errors/e4f20464a3666fb1. Report an issue: GitHub.