remix-run/remix · error · TypeError

files.globalTransforms[${index}] must be a function or objec

Error message

files.globalTransforms[${index}] must be a function or object

What it means

Each element of `files.globalTransforms` must be either a bare transform function or an object definition. This error fires when an entry is null, a primitive (string/number/boolean), or otherwise neither function nor object.

Source

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

      ),
    })
  }

  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`)
    }

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

    normalizedGlobalTransforms.push({
      ...transform,
      extensions: normalizeTransformExtensions(
        transform.extensions,
        `files.globalTransforms[${index}].extensions`,
      ),
    })
  }

View on GitHub (pinned to 9696913134)

Solutions

1. Pass the function itself: `globalTransforms: [minify]` not `['minify']`
2. Filter out falsy entries if the list is built dynamically: `list.filter(Boolean)`
3. For object entries, make sure they include a `transform` function (see adjacent error)

Example fix

// before
files: { globalTransforms: ['minify'] }
// after
import { minify } from './minify.ts'
files: { globalTransforms: [minify] }

files.globalTransforms?.forEach((t, i) => {
  if (typeof t !== 'function' && (t === null || typeof t !== 'object')) {
    throw new Error(`globalTransforms[${i}] must be a function or object`)
  }
})

function isTransformEntry(t: unknown): boolean {
  return typeof t === 'function' || (!!t && typeof t === 'object')
}

When it happens

Trigger: `globalTransforms: ['minify']` (string), `[null]`, or `[42]` — e.g. passing a transform name instead of the imported function.

Common situations: Passing a plugin name string instead of the imported function; sparse arrays from `.map()` on mis-shaped data; optional imports resolving to undefined.

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 must be an array
• files.globalTransforms[${index}].name must be a string

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