gohugoio/hugo · error
id must be set
Error message
id must be set
What it means
`ValidateBatchID` guards every ID used in the js.Batch API (batch names, group names, script/instance/runner IDs) because these IDs become cache keys and output paths. An empty string is rejected outright with this error.
Source
Thrown at internal/js/esbuild/batch.go:154
func (o *opts[K, C]) GetIdentity() identity.Identity {
return o.h
}
func (o *optsHolder[C]) SetOptions(m map[string]any) string {
o.optsSetCounter++
o.optsPrev = o.optsCurr
o.optsCurr = m
o.compiledPrev = o.compiled
o.compiled, o.compileErr = o.compiled.compileOptions(m, o.defaults)
o.checkCompileErr()
return ""
}
// ValidateBatchID validates the given ID according to some very
func ValidateBatchID(id string, isTopLevel bool) error {
if id == "" {
return fmt.Errorf("id must be set")
}
// No Windows slashes.
if strings.Contains(id, "\\") {
return fmt.Errorf("id must not contain backslashes")
}
// Allow forward slashes in top level IDs only.
if !isTopLevel && strings.Contains(id, "/") {
return fmt.Errorf("id must not contain forward slashes")
}
return nil
}
func newIsBuiltOrTouched() isBuiltOrTouched {
return isBuiltOrTouched{
built: make(buildIDs),
touched: make(buildIDs),View on GitHub ↗ (pinned to 8a468df065)
Solutions
- Pass a non-empty ID string to js.Batch/Group/WithScript etc.
- If the ID is computed, guard it: `{{ with $id }}{{ $batch := js.Batch . }}...{{ end }}` or fail loudly with errorf.
- Check the page/site param the ID is derived from is set for every page that renders the template.
Example fix
{{/* before */}}
{{ $batch := js.Batch $.Param "batchid" }}
{{/* after */}}
{{ $id := $.Param "batchid" | default "main" }}
{{ $batch := js.Batch $id }} Defensive patterns
Strategy: validation
Validate before calling
// Before registering a batch script/instance/runner:
if id == "" {
return errors.New("js.Batch script id must be a non-empty string")
} Type guard
func validBatchID(id string) bool {
return id != "" && !strings.ContainsRune(id, '\\')
} Prevention
- Always pass an explicit, stable id as the first argument to Group/Script/Instance calls in js.Batch templates.
- Derive ids from known values (page path, script name), and verify the deriving expression can't produce empty for any page.
- Guard templated ids: {{ if not $id }}{{ errorf "missing batch id" }}{{ end }}.
When it happens
Trigger: Calling `js.Batch ""`, `.Group ""`, or adding a script/instance/runner with an empty ID — e.g. `{{ $batch := js.Batch "" }}` or an ID templated from a variable/param that evaluates to empty.
Common situations: Deriving the ID from a page param or `.File.BaseFileName` that is unset for some pages; refactoring that drops a hardcoded ID; passing the wrong variable to the batch call.
Related errors
- id must not contain backslashes
- id must not contain forward slashes
- redirects must have either From or FromRe set
- failed to create config from result: %w
- failed to create config: %w
AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31).
Data as JSON: /data/errors/ccf800ff35c83e13.json.
Report an issue: GitHub ↗.