What causes "failed to build JS bundle: %w" in gohugoio/hugo?

Inspect the wrapped esbuild error messages — they include the resolved source file and line; fix the reported syntax/import problem.

gohugoio/hugo · error

failed to build JS bundle: %w

Error message

failed to build JS bundle: %w

What it means

Wrapper around the actual esbuild invocation inside a batch build: after assembling entry points, virtual-import resolvers, and load hooks, Hugo calls `buildClient.Build(jsOpts)`. If esbuild reports errors (syntax errors, unresolvable imports, loader failures), they are wrapped with this message. It sits beneath error 525 in the chain.

Source

Thrown at internal/js/esbuild/batch.go:625

				}
				return nil
			},
			ResolveSourceMapSource: func(s string) string {
				if r, found := state.importResource.Get(s); found {
					if ss := resources.InternalResourceSourcePath(r); ss != "" {
						return ss
					}
					return PrefixHugoMemory + s
				}
				return ""
			},
			EntryPoints: entryPoints,
		},
	}

	result, err := b.client.buildClient.Build(jsOpts)
	if err != nil {
		return nil, fmt.Errorf("failed to build JS bundle: %w", err)
	}

	groups := make(map[string]resource.Resources)

	createAndAddResource := func(targetPath, group string, o api.OutputFile, mt media.Type) error {
		var sourceFilename string
		if r, found := state.importResource.Get(targetPath); found {
			sourceFilename = resources.InternalResourceSourcePathBestEffort(r)
		}
		targetPath = path.Join(b.id, targetPath)

		rd := resources.ResourceSourceDescriptor{
			LazyPublish: true,
			OpenReadSeekCloser: func() (hugio.ReadSeekCloser, error) {
				return hugio.NewReadSeekerNoOpCloserFromBytes(o.Contents), nil
			},
			MediaType:            mt,
			TargetPath:           targetPath,

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Inspect the wrapped esbuild error messages — they include the resolved source file and line; fix the reported syntax/import problem.
Run `npm install` (or equivalent) so bare-specifier imports resolve from node_modules.
Check that resource imports in batched scripts point at real assets and that params/instances are registered before the build.

Defensive patterns

Strategy: try-catch

Try / catch

{{ with try (resources.Get "js/main.js" | js.Build $opts) }}
  {{ with .Err }}{{ errorf "JS bundle failed: %s" . }}{{ else }}
    <script src="{{ .Value.RelPermalink }}"></script>
  {{ end }}
{{ end }}

Prevention

Read the wrapped esbuild diagnostics — they name the exact file/line (missing import, TS syntax error, bad loader).
Run npm install (or equivalent) before hugo when scripts import node_modules packages.
Configure defines/shims for browser builds of packages that reference process.env.
Treat bundle errors as build failures; never fall back to serving stale bundled output.

When it happens

Trigger: Any esbuild compile/bundle failure of the batch's combined entry points: a JS/TS syntax error in a batched script or runner, an import that neither the virtual Hugo resource resolver nor node_modules can satisfy, or a failing OnLoad reading a resource's content.

Common situations: Missing npm dependencies after cloning a site without running npm install; importing a Hugo resource path that doesn't exist so resolution falls through; TypeScript syntax in a file with a .js extension; version bumps changing script APIs.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/544e3cac5dd986b5.json. Report an issue: GitHub ↗.