remix-run/remix · error · AssetServerCompilationError

LOADER_FAILED

LOADER_FAILED

Error message

Module loader failed for ${loaderUrl}. ${formatUnknownError(error)}

What it means

After the initial transform, module loaders run and any exception escaping them (other than pre-wrapped compilation errors) is rethrown as LOADER_FAILED for the specific loaderUrl. The formatted original error is embedded, so the message tells you which loader stage failed and why.

Source

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

  if (options.loaders.length > 0) {
    let loaderUrl = pathToFileURL(resolvedPath).href
    let loaderInputSource = sourceMap ? appendInlineSourceMap(rawCode, sourceMap) : rawCode
    let loaderOutputSource: string
    try {
      let loaderResult = runModuleLoaders(loaderUrl, {
        format: 'module',
        loaders: options.loaders,
        moduleUrl: options.moduleUrl,
        source: loaderInputSource,
      })
      loaderOutputSource = moduleLoadSourceToString(getModuleLoadSource(loaderUrl, loaderResult))
    } catch (error) {
      if (isAssetServerCompilationError(error)) throw error
      throw createAssetServerCompilationError(
        `Module loader failed for ${loaderUrl}. ${formatUnknownError(error)}`,
        {
          cause: error,
          code: 'LOADER_FAILED',
        },
      )
    }
    if (loaderOutputSource !== loaderInputSource) {
      let loaderOutput = extractInlineSourceMap(loaderOutputSource)
      rawCode = loaderOutput.code.trimEnd()
      sourceMap =
        loaderOutput.sourceMap && loaderOutput.sourceMap !== sourceMap
          ? sourceMap
            ? composeSourceMaps(loaderOutput.sourceMap, sourceMap)
            : loaderOutput.sourceMap
          : null
    }
  }

  if (options.minify) {
    let minifyResult = await minifyModule(rawCode, resolvedPath, options.target, options.sourceMaps)
    rawCode = minifyResult.code.trimEnd()

View on GitHub (pinned to 9696913134)

Solutions

Read the full message and error.cause to identify which loader threw and why
Fix the loader's handling for that file type/URL, or narrow the loader's matching pattern so it doesn't apply to the failing module
Verify the input file the loader tried to read exists and is readable at loaderUrl
Pin/upgrade the loader package to a version compatible with this pipeline

Defensive patterns

Strategy: try-catch

Validate before calling

// in dev, smoke-test each loader with a known-good module before wiring into the chain

Try / catch

catch (e) {
  if (isAssetServerCompilationError(e) && e.code === 'LOADER_FAILED') {
    // message names loaderUrl and embeds the loader's own error — surface both
  }
}

Prevention

Scope each loader narrowly by extension/URL pattern
Handle fetch/read failures inside the loader with clear errors instead of letting them escape
Write unit tests per loader over the file types it claims

When it happens

Trigger: A registered module loader throwing during load/transform of a module — e.g. a loader that can't fetch its input, a loader with a bug, or a loader applying an incompatible transform (CSS loader on JS, etc.).

Common situations: Custom loaders hitting filesystem/network failures; loader version skew after upgrades; loaders assuming a format (TS, JSON, CSS) that doesn't match the file extension; loaders with unhandled edge cases on empty or generated files.

Related errors

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