remix-run/remix · error · TypeError

files.globalTransforms[${index}].name must be a string

Error message

files.globalTransforms[${index}].name must be a string

What it means

When a `files.globalTransforms` entry is an object, its optional `name` field (used for logging/identification) must be a string if present. This error fires when `name` is set to a non-string value such as a number, boolean, or object.

Source

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

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

  let maxRequestTransforms = files.maxRequestTransforms ?? defaultMaxRequestTransforms
  if (!Number.isInteger(maxRequestTransforms) || maxRequestTransforms < 1) {
    throw new TypeError('files.maxRequestTransforms must be a positive integer')

View on GitHub (pinned to 9696913134)

Solutions

1. Make `name` a string (`{ name: 'minify', transform: fn }`) or remove the field entirely
2. Coerce dynamic names: `{ name: String(id), transform: fn }`

Example fix

// before
files: { globalTransforms: [{ name: 1, transform: fn }] }
// after
files: { globalTransforms: [{ name: 'minify', transform: fn }] }

if ('name' in t && t.name !== undefined && typeof t.name !== 'string') {
  t.name = String(t.name)
}

function hasValidName(t: { name?: unknown }): boolean {
  return t.name === undefined || typeof t.name === 'string'
}

When it happens

Trigger: `globalTransforms: [{ name: 1, transform: fn }]` or any object entry whose `name` property is defined but not a string.

Common situations: Names derived from counters or enums (numbers); booleans from config toggles accidentally assigned to `name`; spread objects carrying an unexpected `name` key.

Related errors

• files.transforms must be an object
• files.transforms keys must use "transform-name" format. Rece
• files.transforms.${name} must define a transform() function
• files.transforms.${name}.param must be true or "optional"
• files.globalTransforms must be an array

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