remix-run/remix · error · AssetServerCompilationError

TRANSFORM_FAILED

TRANSFORM_FAILED

Error message

Failed to analyze HMR usage in transformed script. ${parseResult.errors[0]?.message ?? 'Unknown parse error'}

What it means

After transforming a script, the pipeline re-parses the output to detect `import.meta.hot` usage for HMR analysis. If the parser reports errors on the transformed output, the HMR analysis cannot proceed and TRANSFORM_FAILED is thrown with the first parser message. This indicates the transform itself produced invalid JavaScript, not that the original source was invalid.

Source

Thrown at packages/assets/src/lib/scripts/transform.ts:324

export function getHmrAnalysis(rawCode: string): TransformedModule['hmr'] {
  let mayUseImportMetaHot = rawCode.includes('import.meta.hot')
  let usesImportMetaHot = false
  let acceptedDeps: HmrAcceptedDependency[] = []
  let selfAccepting = false

  if (mayUseImportMetaHot) {
    try {
      let parseResult = parseSync('hmr-analysis.js', rawCode, {
        lang: 'js',
        sourceType: 'module',
      })

      if (parseResult.errors.length > 0) {
        throw createAssetServerCompilationError(
          `Failed to analyze HMR usage in transformed script. ${parseResult.errors[0]?.message ?? 'Unknown parse error'}`,
          {
            code: 'TRANSFORM_FAILED',
          },
        )
      }

      walkAst(parseResult.program, (node) => {
        if (isImportMetaHotNode(node)) {
          usesImportMetaHot = true
        }

        if (node.type !== 'CallExpression') return
        if (!isImportMetaHotAcceptCallee(node.callee)) return

        let [firstArgument] = node.arguments
        if (firstArgument === undefined || !isAcceptedDependencyArgument(firstArgument)) {
          selfAccepting = true
          return
        }

View on GitHub (pinned to 9696913134)

Solutions

1. Inspect the full transformed output for the failing module (log the code passed to parse) and fix the loader/transform that emits invalid syntax
2. Update or remove custom module loaders implicated in the chain; check loader version compatibility
3. If using a minifier/other transform, run it after HMR analysis or configure it to emit parseable ES output
4. Report/check upstream if the unmodified pipeline fails on valid ESM input

catch (e) {
  if (isAssetServerCompilationError(e) && e.code === 'TRANSFORM_FAILED') {
    logger.error(`HMR parse failed: ${e.message}`, e.cause)
    // disable the implicated loader or fall back to serving untransformed ESM
  } else throw e
}

When it happens

Trigger: getHmrAnalysis running parse on transformed code that no longer parses — typically caused by a transform/loader emitting syntax the configured parser rejects, or a broken source-map-preserving rewrite (e.g. from a custom module loader or minifier step).

Common situations: Custom module loaders (runModuleLoaders chain) that return code with unbalanced braces or target syntax beyond the parser's configured ECMA version; incompatible plugin/loader versions after an upgrade; injected HMR preamble snippets that corrupt the output.

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

• COMMONJS_NOT_SUPPORTED
• FILE_TRANSFORM_NOT_SUPPORTED
• hmr must create a channel with a close function
• hmr must create a channel with an onFileEvents function
• hmr must create a channel with an updateWatchedFiles functio

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