remix-run/remix · error · TypeError

files.globalTransforms must be an array

Error message

files.globalTransforms must be an array

What it means

`files.globalTransforms` must be an array of transform functions or transform-definition objects applied to all matching files. This error fires when it is set to a non-array value such as a single function, an object, or a string.

Source

Thrown at packages/assets/src/lib/files/config.ts:258

      transform.param !== undefined &&
      transform.param !== true &&
      transform.param !== 'optional'
    ) {
      throw new TypeError(`files.transforms.${name}.param must be true or "optional"`)
    }

    normalizedTransforms.set(name, {
      ...transform,
      extensions: normalizeTransformExtensions(
        transform.extensions,
        `files.transforms.${name}.extensions`,
      ),
    })
  }

  let globalTransforms = files.globalTransforms ?? []
  if (!Array.isArray(globalTransforms)) {
    throw new TypeError('files.globalTransforms must be an array')
  }

  let normalizedGlobalTransforms: ResolvedAssetGlobalTransform[] = []

  for (let [index, transform] of globalTransforms.entries()) {
    if (typeof transform === 'function') {
      normalizedGlobalTransforms.push({ transform })
      continue
    }

    if (transform === null || typeof transform !== 'object') {
      throw new TypeError(`files.globalTransforms[${index}] must be a function or object`)
    }

    if ('name' in transform && transform.name !== undefined && typeof transform.name !== 'string') {
      throw new TypeError(`files.globalTransforms[${index}].name must be a string`)
    }

View on GitHub (pinned to 9696913134)

Solutions

1. Wrap in an array: `globalTransforms: [fn]`
2. For named, URL-addressable transforms use the `files.transforms` object map instead

Example fix

// before
files: { globalTransforms: minify }
// after
files: { globalTransforms: [minify] }

if (files.globalTransforms !== undefined && !Array.isArray(files.globalTransforms)) {
  throw new Error('files.globalTransforms must be an array')
}

function isGlobalTransformList(v: unknown): v is unknown[] {
  return Array.isArray(v)
}

When it happens

Trigger: Passing `globalTransforms: fn` (a bare function), an object map, or other non-array value under `files`.

Common situations: Confusing the array-based `globalTransforms` with the map-based `transforms`; passing a single transform without wrapping it in an array.

Related errors

• files.transforms must be an object
• files.transforms.${name} must define a transform() function
• files.transforms.${name}.param must be true or "optional"
• files.globalTransforms[${index}] must be a function or objec
• files.globalTransforms[${index}].name must be a string

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/e85514348b7ba377. Report an issue: GitHub.