transloadit/uppy · error · ErrorWithCause

Transloadit: The `params` option is a malformed JSON string.

Error message

Transloadit: The `params` option is a malformed JSON string.

What it means

Thrown when the Transloadit params option is supplied as a JSON string but JSON.parse fails. It wraps the parse error via ErrorWithCause (cause preserved), and the message stresses this is a user-input bug, not an Uppy/Transloadit bug. Validation happens in validateParams during upload preparation.

Source

Thrown at packages/@uppy/transloadit/src/index.ts:184

const sendErrorToConsole = (originalErr: Error) => (err: Error) => {
  const error = new ErrorWithCause('Failed to send error to the client', {
    cause: err,
  })
  console.error(error, originalErr)
}

function validateParams(params?: AssemblyOptions['params']): void {
  if (params == null) {
    throw new Error('Transloadit: The `params` option is required.')
  }

  let parsed: AssemblyParameters
  if (typeof params === 'string') {
    try {
      parsed = JSON.parse(params) as AssemblyParameters
    } catch (err) {
      // Tell the user that this is not an Uppy bug!
      throw new ErrorWithCause(
        'Transloadit: The `params` option is a malformed JSON string.',
        { cause: err },
      )
    }
  } else {
    parsed = params
  }

  if (!parsed.auth?.key) {
    throw new Error(
      'Transloadit: The `params.auth.key` option is required. ' +
        'You can find your Transloadit API key at https://transloadit.com/c/template-credentials',
    )
  }
}

function ensureAssemblyId(status: AssemblyResponse): string {
  if (!status.assembly_id) {

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Validate the string with JSON.parse at config-load time to fail early with the real parse error
2. Pass params as an object literal instead of a string — no parsing involved
3. Use a JSON linter/validator on the embedded string; watch for smart quotes and comments (not valid JSON)
4. If params come from an env var/endpoint, JSON.parse and log a clear config error before Uppy boots

Example fix

// before
uppy.use(Transloadit, {
  params: `{ "auth": {"key": "..."}, steps: {...} }`, // unquoted keys -> throw
})

// after
uppy.use(Transloadit, {
  params: {
    auth: { key: process.env.TRANSLOADIT_KEY },
    steps: { encode: { robot: '/video/encode', preset: 'ipad-high' } },
  },
})

const paramsString = process.env.TRANSLOADIT_PARAMS!
const parsed = JSON.parse(paramsString) // fail fast with the real parse error
uppy.use(Transloadit, { params: parsed })

null

try { JSON.parse(paramsString) } catch (err) {
  console.error('Invalid Transloadit params JSON', err)
  // fix config before calling uppy.upload()
}

When it happens

Trigger: Passing params as a string like "{steps: ...}" (unquoted keys), with trailing commas, smart quotes pasted from a doc, or truncated JSON; then calling uppy.upload().

Common situations: Copy-pasting Assembly instructions JSON from tutorials with typographic quotes; building the JSON via string concatenation that breaks escaping; a template engine or env var mangling quotes.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Transloadit: The `params` option is required.
• Transloadit: The `params.auth.key` option is required. You c
• ThumbnailGenerator: The `lazy` and `waitForThumbnailsBeforeU
• Transloadit: Assembly status is missing `assembly_id`.
• Transloadit: Assembly status is missing ${label}.

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