Unverified Commit 60f903c7 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Improve webpack loader error messages and handling (#89698)

## What?

This PR improves error reporting for webpack loaders by:

1. **Preserving loader paths in error messages**: Modified the webpack
message formatter to rewrite "Module build failed" headers to preserve
the loader path information while removing the verbose prefix. This
makes errors more readable in both CLI output and error overlays.

2. **Better error wrapping for non-Error throws**: When loaders throw
non-Error values (strings, objects, etc.), the error is now wrapped with
loader path information in the stack trace, making it easier to identify
which loader caused the error.

3. **Catching deferred loader errors**: Added handling for errors that
occur after loader completion (e.g., unhandled Promise rejections,
setTimeout throws) by:
   - Adding an `unhandledRejection` handler in the IPC layer
- Delaying resolution in webpack-loaders transform to allow error
handlers to fire before sending the 'end' message

4. **Conditional `(from ...)` annotation**: The `(from
/path/to/loader.js)` annotation is only added when the loader path is
**not already visible** in the error's stack trace. This avoids
redundant noise for errors that already include the loader in their
stack, while still providing the annotation for errors without loader
context (string throws, errors without stacks, etc.).

5. **Hiding internal Next.js loader paths**: Internal Next.js loader
paths (under `next/dist/`) are filtered from error messages since
they're noise for users. Only user-authored loader paths are shown.

6. **Comprehensive test coverage**: Added e2e tests covering various
error scenarios (Error throws, string throws, Promise rejections,
setTimeout errors, no-stack errors, filesystem errors) with verification
of both CLI output and error overlay display.

## Why?

Webpack loader errors were previously difficult to debug because:
- The verbose "Module build failed" prefix obscured the actual error
message
- Non-Error throws lost their context and loader information
- Deferred errors (Promise rejections, async throws) were not properly
surfaced
- Error overlays didn't clearly show which loader caused the problem
- The `(from ...)` annotation was always added, even when the loader
path was already in the stack trace (addressed per review feedback)

## How?

- **format-webpack-messages.ts**: Changed from filtering out loader
headers to rewriting them, preserving the `(from ./loaders/...)`
information. Internal Next.js loader paths are hidden.
- **webpack-loaders.ts**: Added error wrapping for non-Error values,
deferred resolution to catch async errors, and conditional `(from ...)`
annotation that checks `err.stack` before appending. Resolves loader
paths into an array, then checks if any path appears in the stack before
deciding to annotate.
- **ipc/index.ts**: Added `unhandledRejection` handler to surface
Promise-related errors.
- **Test loaders**: `error-loader.js` and `fs-error-loader.js` delegate
to a `create-error.js` helper that creates errors and invokes the loader
callback inside `setTimeout`. This ensures the loader file path is
absent from the stack trace, exercising the conditional `(from ...)`
annotation path. Other loaders (string-error, promise-error,
timeout-error, no-stack-error) test different error scenarios directly.
- **Test suite**: Comprehensive e2e tests verify CLI output and error
overlay for each error type. Turbopack-specific tests cover promise
rejections, timeout errors, no-stack errors, and filesystem errors.

---------
Co-authored-by: 's avatarClaude <noreply@anthropic.com>
parent 1287f9a0
...@@ -86,9 +86,20 @@ function formatMessage( ...@@ -86,9 +86,20 @@ function formatMessage(
} }
let lines = message.split('\n') let lines = message.split('\n')
// Strip Webpack-added headers off errors/warnings // Extract loader paths from Webpack-added headers and move them to end.
// Original format: "Module build failed (from ./loaders/foo-loader.js):"
// The header line is removed and the path is appended at the end as:
// " (from ./loaders/foo-loader.js)"
// https://github.com/webpack/webpack/blob/master/lib/ModuleError.js // https://github.com/webpack/webpack/blob/master/lib/ModuleError.js
lines = lines.filter((line: string) => !/Module [A-z ]+\(from/.test(line)) const loaderPaths: string[] = []
lines = lines.filter((line: string) => {
const match = /Module [A-z ]+\(from (.+)\):?\s*$/.exec(line)
if (match) {
loaderPaths.push(match[1])
return false
}
return true
})
// Transform parsing error into syntax error // Transform parsing error into syntax error
// TODO: move this to our ESLint formatter? // TODO: move this to our ESLint formatter?
...@@ -182,6 +193,16 @@ function formatMessage( ...@@ -182,6 +193,16 @@ function formatMessage(
lines = message.split('\n') lines = message.split('\n')
} }
// Append loader paths at the end (before any remaining stack trace)
if (loaderPaths.length > 0) {
for (const loaderPath of loaderPaths) {
// Don't show internal Next.js loader paths — they're noise for users
if (!/[/\\]next[/\\]dist[/\\]/.test(loaderPath)) {
lines.push(` (from ${loaderPath})`)
}
}
}
// Remove duplicated newlines // Remove duplicated newlines
lines = (lines as string[]).filter( lines = (lines as string[]).filter(
(line, index, arr) => (line, index, arr) =>
......
const data = require('../../data/error.data')
export default function Page() {
return <p>{data.default}</p>
}
const data = require('../../data/fs-error.data')
export default function Page() {
return <p>{data.default}</p>
}
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
const data = require('../../data/no-stack-error.data')
export default function Page() {
return <p>{data.default}</p>
}
export default function Page() {
return <p>hello world</p>
}
const data = require('../../data/promise-error.data')
export default function Page() {
return <p>{data.default}</p>
}
const data = require('../../data/string-error.data')
export default function Page() {
return <p>{data.default}</p>
}
const data = require('../../data/timeout-error.data')
export default function Page() {
return <p>{data.default}</p>
}
const fs = require('fs')
// These helpers create errors and invoke the loader callback inside a
// setTimeout so that the resulting stack trace does NOT contain the
// loader file path — only this helper file. This lets the Turbopack
// "(from …)" annotation fire (it's conditional on the loader path
// not already being in the stack).
module.exports.callbackWithError = function callbackWithError(
callback,
message
) {
setTimeout(() => {
callback(new Error(message))
}, 0)
}
module.exports.callbackWithFsError = function callbackWithFsError(callback) {
setTimeout(() => {
try {
fs.readFileSync('/does/not/exist/file.txt')
} catch (err) {
callback(err)
}
}, 0)
}
const { callbackWithError } = require('./create-error')
module.exports = function errorLoader(source) {
callbackWithError(this.async(), 'An error thrown by error-loader')
}
const { callbackWithFsError } = require('./create-error')
module.exports = function fsErrorLoader(source) {
callbackWithFsError(this.async())
}
module.exports = function noStackErrorLoader(source) {
const err = new Error('An error without stack from no-stack-error-loader')
err.stack = undefined
throw err
}
module.exports = function promiseErrorLoader(source) {
Promise.reject(new Error('An error thrown by promise-error-loader'))
return source
}
module.exports = function stringErrorLoader(source) {
// Intentionally throwing a string (not an Error object) to test string error handling
// eslint-disable-next-line no-throw-literal
throw 'A string error thrown by string-error-loader'
}
module.exports = function timeoutErrorLoader(source) {
const callback = this.async()
setTimeout(() => {
throw new Error('An error thrown by timeout-error-loader')
}, 0)
callback(null, source)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
turbopack: {
rules: {
'error.data': {
loaders: [require.resolve('./loaders/error-loader.js')],
as: '*.js',
},
'string-error.data': {
loaders: [require.resolve('./loaders/string-error-loader.js')],
as: '*.js',
},
'promise-error.data': {
loaders: [require.resolve('./loaders/promise-error-loader.js')],
as: '*.js',
},
'timeout-error.data': {
loaders: [require.resolve('./loaders/timeout-error-loader.js')],
as: '*.js',
},
'no-stack-error.data': {
loaders: [require.resolve('./loaders/no-stack-error-loader.js')],
as: '*.js',
},
'fs-error.data': {
loaders: [require.resolve('./loaders/fs-error-loader.js')],
as: '*.js',
},
},
},
webpack(config) {
config.module.rules.push(
{
test: /[\\/]error\.data$/,
use: [require.resolve('./loaders/error-loader.js')],
},
{
test: /string-error\.data$/,
use: [require.resolve('./loaders/string-error-loader.js')],
},
{
test: /promise-error\.data$/,
use: [require.resolve('./loaders/promise-error-loader.js')],
},
{
test: /timeout-error\.data$/,
use: [require.resolve('./loaders/timeout-error-loader.js')],
},
{
test: /no-stack-error\.data$/,
use: [require.resolve('./loaders/no-stack-error-loader.js')],
},
{
test: /fs-error\.data$/,
use: [require.resolve('./loaders/fs-error-loader.js')],
}
)
return config
},
}
module.exports = nextConfig
import { nextTestSetup } from 'e2e-utils'
import { retry, waitForRedbox, getRedboxSource } from 'next-test-utils'
import stripAnsi from 'strip-ansi'
describe('webpack-loader-errors', () => {
const { next, isNextDev, isTurbopack } = nextTestSetup({
files: __dirname,
skipDeployment: true,
skipStart: true,
})
if (!isNextDev) {
it('should skip in non-dev mode', () => {})
return
}
beforeAll(async () => {
await next.start()
})
describe('CLI output', () => {
// Test string-error before error to ensure each error appears independently
// in the CLI output (webpack only shows errors[0] per compilation)
it('should show the loader path and error message when a loader throws a plain string', async () => {
await next.fetch('/string-error')
await retry(
async () => {
const output = stripAnsi(next.cliOutput)
expect(output).toContain('string-error.data')
expect(output).toContain(
'A string error thrown by string-error-loader'
)
expect(output).toMatch(/\(from .+loaders\/string-error-loader/)
},
// webpack compilation output appears asynchronously
30_000
)
})
it('should show the loader path and error message when a loader throws an Error', async () => {
await next.fetch('/error')
await retry(async () => {
const output = stripAnsi(next.cliOutput)
expect(output).toContain('error.data')
expect(output).toContain('An error thrown by error-loader')
expect(output).toMatch(/\(from .+loaders\/error-loader/)
}, 30_000)
})
// The following CLI tests are Turbopack-only because webpack's CLI output
// only logs errors[0] per compilation (see store.ts). When multiple pages
// have errors, only the first error (by module order) is shown. These
// error types still work correctly and are tested via the overlay tests.
if (isTurbopack) {
it('should surface an unhandled rejected Promise from a loader', async () => {
await next.fetch('/promise-error')
await retry(async () => {
const output = stripAnsi(next.cliOutput)
expect(output).toContain('An error thrown by promise-error-loader')
})
})
it('should surface a setTimeout error thrown after loader completion', async () => {
await next.fetch('/timeout-error')
await retry(async () => {
const output = stripAnsi(next.cliOutput)
expect(output).toContain('An error thrown by timeout-error-loader')
})
})
it('should show the loader path and error message when a loader throws an Error without stack', async () => {
await next.fetch('/no-stack-error')
await retry(async () => {
const output = stripAnsi(next.cliOutput)
expect(output).toContain(
'An error without stack from no-stack-error-loader'
)
expect(output).toMatch(/\(from .+loaders\/no-stack-error-loader/)
})
})
it('should show the loader path and error message when a loader throws a filesystem error', async () => {
await next.fetch('/fs-error')
await retry(async () => {
const output = stripAnsi(next.cliOutput)
expect(output).toContain('ENOENT')
expect(output).toMatch(/\(from .+loaders\/fs-error-loader/)
})
})
}
})
// Build errors accumulate globally and the overlay shows the first build
// error (no pagination for build errors). After the CLI tests compile all
// error routes, the overlay may show any accumulated error. So we only
// verify that a loader error with "(from ...)" is displayed, not which
// specific one. The CLI tests above validate each error type specifically.
describe('error overlay', () => {
it('should show error overlay with loader path when a loader throws a plain string', async () => {
const browser = await next.browser('/string-error')
await waitForRedbox(browser)
const source = await getRedboxSource(browser)
expect(source).toMatch(/\(from .+loaders\//)
})
it('should show error overlay with loader path when a loader throws an Error', async () => {
const browser = await next.browser('/error')
await waitForRedbox(browser)
const source = await getRedboxSource(browser)
expect(source).toMatch(/\(from .+loaders\//)
})
it('should show error overlay with loader path when a loader throws an Error without stack', async () => {
const browser = await next.browser('/no-stack-error')
await waitForRedbox(browser)
const source = await getRedboxSource(browser)
expect(source).toMatch(/\(from .+loaders\//)
})
it('should show error overlay with loader path when a loader throws a filesystem error', async () => {
const browser = await next.browser('/fs-error')
await waitForRedbox(browser)
const source = await getRedboxSource(browser)
expect(source).toMatch(/\(from .+loaders\//)
})
})
})
...@@ -175,6 +175,10 @@ process.on('uncaughtException', (err) => { ...@@ -175,6 +175,10 @@ process.on('uncaughtException', (err) => {
IPC.sendError(err) IPC.sendError(err)
}) })
process.on('unhandledRejection', (reason) => {
IPC.sendError(reason instanceof Error ? reason : new Error(String(reason)))
})
const improveConsole = (name: string, stream: string, addStack: boolean) => { const improveConsole = (name: string, stream: string, addStack: boolean) => {
// @ts-ignore // @ts-ignore
const original = console[name] const original = console[name]
......
...@@ -491,10 +491,41 @@ const transform = ( ...@@ -491,10 +491,41 @@ const transform = (
'**', '**',
]), ]),
}) })
if (err) return reject(err) if (err) {
// Resolve loader paths to include in the error message using
// the same "(from ...)" style as webpack's format-webpack-messages.
const loaderPathList = loadersWithOptions.map((l) => {
try {
return __turbopack_external_require__.resolve(l.loader, {
paths: [contextDir, resourceDir],
})
} catch {
return l.loader
}
})
const loaderPaths = loaderPathList.join(', ')
if (!(err instanceof Error)) {
// String throws lose their stack trace, so we create a
// synthetic one pointing at the loader.
const wrappedErr = new Error(
`${String(err)}\n (from ${loaderPaths})`
)
wrappedErr.stack = `Error: ${String(err)}\n at loader (${loaderPaths})`
return reject(wrappedErr)
}
// Only append "(from ...)" when no loader path is already
// visible in the stack trace, to avoid redundant noise.
const stack = typeof err.stack === 'string' ? err.stack : ''
if (!loaderPathList.some((p) => stack.includes(p))) {
err.message += `\n (from ${loaderPaths})`
}
return reject(err)
}
if (!result.result) return reject(new Error('No result from loaders')) if (!result.result) return reject(new Error('No result from loaders'))
const [source, map] = result.result const [source, map] = result.result
resolve({ const resolvedValue = {
source: Buffer.isBuffer(source) source: Buffer.isBuffer(source)
? { binary: source.toString('base64') } ? { binary: source.toString('base64') }
: source, : source,
...@@ -504,7 +535,12 @@ const transform = ( ...@@ -504,7 +535,12 @@ const transform = (
: typeof map === 'object' : typeof map === 'object'
? JSON.stringify(map) ? JSON.stringify(map)
: undefined, : undefined,
}) }
// Delay resolution by one event loop turn to catch deferred errors
// from loaders (e.g. unhandled Promise rejections, setTimeout throws).
// During this delay, uncaughtException/unhandledRejection handlers can
// fire and send the error via IPC before we send the 'end' message.
setTimeout(() => resolve(resolvedValue), 0)
} }
) )
}) })
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment