remix-run/remix · error · TypeError

files.transforms keys must use "transform-name" format. Rece

Error message

files.transforms keys must use "transform-name" format. Received "${name}".

What it means

Keys in the `files.transforms` map become URL segments (e.g. `/transform-name/file.ext`), so each name must match `[A-Za-z0-9_-]+` — no dots, slashes, spaces, or unicode. This error fires for keys like `md.min`, `my transform`, or `md/v2`.

Source

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

    if (seen.has(normalizedExtension)) continue
    seen.add(normalizedExtension)
    normalizedExtensions.push(normalizedExtension)
  }

  let transforms = files.transforms ?? {}
  if (transforms === null || typeof transforms !== 'object' || Array.isArray(transforms)) {
    throw new TypeError('files.transforms must be an object')
  }

  let normalizedTransforms = new Map<
    string,
    AssetRequestTransform<string, AssetRequestTransformParamMode>
  >()

  for (let [name, transform] of Object.entries(transforms)) {
    if (!/^[A-Za-z0-9_-]+$/.test(name)) {
      throw new TypeError(
        `files.transforms keys must use "transform-name" format. Received "${name}".`,
      )
    }

    if (
      transform === null ||
      typeof transform !== 'object' ||
      typeof transform.transform !== 'function'
    ) {
      throw new TypeError(`files.transforms.${name} must define a transform() function`)
    }

    if (
      'param' in transform &&
      transform.param !== undefined &&
      transform.param !== true &&
      transform.param !== 'optional'
    ) {

View on GitHub (pinned to 9696913134)

Solutions

1. Rename keys to use only letters, digits, `_`, and `-`, e.g. `md`, `minify-md`
2. Strip invalid characters before building config if names come from user input: `name.replace(/[^A-Za-z0-9_-]/g, '')`

Example fix

// before
files: { transforms: { 'md.min': { transform: fn } } }
// after
files: { transforms: { 'md-min': { transform: fn } } }

if (!/^[A-Za-z0-9_-]+$/.test(name)) {
  throw new Error(`transform name "${name}" must use [A-Za-z0-9_-] only`)
}

function isValidTransformName(name: string): boolean {
  return /^[A-Za-z0-9_-]+$/.test(name)
}

When it happens

Trigger: Naming a transform with characters that cannot appear in a URL path segment, such as dots, spaces, slashes, or punctuation.

Common situations: Naming transforms after file extensions (`'.md'` as a key); names copied from display labels with spaces; versioned names like `md@2`.

Related errors

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

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