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

Read the wrapped error after the batch ID — it names the actual failure (compile error, bad option, unresolved import) — and fix that root cause.

gohugoio/hugo · error

failed to build JS batch %q: %w

Error message

failed to build JS batch %q: %w

What it means

Wrapper error from `batcher.Build`, which builds a named `js.Batch` group through a dynacache store. Any failure inside the batch build — invalid options, esbuild compile errors, unresolved imports, script/instance validation — is wrapped with the batch ID via %w, so this is a context frame around an underlying cause.

Source

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

	client            *BatcherClient
	dependencyManager identity.Manager

	configOptions optionsGetSetter[scriptID, configOptions]

	// The last successfully built package.
	// If this is non-nil and not stale, we can reuse it (e.g. on server rebuilds)
	prevBuild *Package
}

// Build builds the batch if not already built or if it's stale.
func (b *batcher) Build(ctx context.Context) (js.BatchPackage, error) {
	key := dynacache.CleanKey(b.id + ".js")
	p, err := b.client.bundlesStore.GetOrCreate(key, func() (js.BatchPackage, error) {
		return b.build(ctx)
	})
	if err != nil {
		return nil, fmt.Errorf("failed to build JS batch %q: %w", b.id, err)
	}
	return p, nil
}

func (b *batcher) Config(ctx context.Context) js.OptionsSetter {
	return b.configOptions.Get(b.buildCount)
}

func (b *batcher) Group(ctx context.Context, id string) js.BatcherGroup {
	if err := ValidateBatchID(id, false); err != nil {
		panic(err)
	}

	b.mu.Lock()
	defer b.mu.Unlock()

	group, found := b.scriptGroups[id]
	if !found {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Read the wrapped error after the batch ID — it names the actual failure (compile error, bad option, unresolved import) — and fix that root cause.
Run `hugo --logLevel debug` or `hugo server` to see the full esbuild diagnostics with file/line locations.
Verify the batch's config options (format, defines, etc.) are valid and that all imported packages exist.

Defensive patterns

Strategy: try-catch

Try / catch

// Template-level: use try when consuming a JS batch group
{{ with try (js.Batch "mybatch") }}
  {{ with .Err }}{{ errorf "JS batch failed: %s" . }}{{ else }}{{/* use .Value */}}{{ end }}
{{ end }}

Prevention

This error wraps an underlying esbuild failure — read the wrapped message; the root cause is usually a syntax error or unresolvable import in one of the batch's scripts.
Keep each batch script compiling standalone; test with hugo server before committing.
Pin JS dependency versions so imports don't break between builds.
Fail the build loudly (errorf) rather than emitting a page without its scripts.

When it happens

Trigger: Executing a template that renders a `js.Batch "someid"` whose build fails: a syntax error in a batched script, a bad option in the batch config (see errors 520–524, 526), a missing import, or an esbuild bundling failure.

Common situations: Refactoring batched JS and introducing a compile error; misconfigured batch group options; imports of npm packages not installed in node_modules; stale cache issues on server rebuilds are handled, so the wrapped error is almost always a real build problem.

Related errors

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