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.

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
• Asset configuration is missing from remix.json.
• Browser HMR is disabled for this node-hmr runtime
• ${errors.map((error) => error.message).join('\n')}

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

Appendix: 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)