gohugoio/hugo · error

unsupported script output format: %q

Error message

unsupported script output format: %q

What it means

Hugo maps the user-supplied `format` option to esbuild's output format when compiling JS via `js.Build`/`js.Batch`. Only `iife` (default when empty), `esm`, and `cjs` are accepted; any other string hits the default switch case in `toBuildOptions` and aborts option compilation with this error.

Source

Thrown at internal/js/esbuild/options.go:354

		loader = api.LoaderJSX
	case media.Builtin.CSSType.SubType:
		loader = api.LoaderCSS
	default:
		err = fmt.Errorf("unsupported Media Type: %q", opts.MediaType)
		return
	}

	var format api.Format
	// One of: iife, cjs, esm
	switch opts.Format {
	case "", "iife":
		format = api.FormatIIFE
	case "esm":
		format = api.FormatESModule
	case "cjs":
		format = api.FormatCommonJS
	default:
		err = fmt.Errorf("unsupported script output format: %q", opts.Format)
		return
	}

	var jsx api.JSX
	switch opts.JSX {
	case "", "transform":
		jsx = api.JSXTransform
	case "preserve":
		jsx = api.JSXPreserve
	case "automatic":
		jsx = api.JSXAutomatic
	default:
		err = fmt.Errorf("unsupported jsx type: %q", opts.JSX)
		return
	}

	var platform api.Platform
	switch opts.Platform {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Change the `format` option in your js.Build/js.Batch call to one of "iife", "esm", or "cjs".
2. Remove the option entirely to get the default IIFE output.
3. If the value comes from site params, verify the param spelling and value in hugo.toml/yaml.

Example fix

{{/* before */}}
{{ $js := resources.Get "main.js" | js.Build (dict "format" "module") }}
{{/* after */}}
{{ $js := resources.Get "main.js" | js.Build (dict "format" "esm") }}

// Go caller / template author: check format before invoking js.Build
validFormats := map[string]bool{"iife": true, "cjs": true, "esm": true}
if !validFormats[opts.Format] {
    return fmt.Errorf("invalid script output format %q; must be one of iife, cjs, esm", opts.Format)
}

When it happens

Trigger: Calling `resources.Get "index.js" | js.Build (dict "format" "umd")` or any format value other than "", "iife", "esm", "cjs" in the options dict passed to js.Build, or in a batch group's script options / config.

Common situations: Typos like "es6", "module", or "commonjs" instead of "cjs"; copying webpack/rollup config values ("umd", "amd") that esbuild-in-Hugo doesn't support; templating the format from site params where the param is unset to an unexpected value.

Related errors

• inject: absolute paths not supported, must be relative to /a
• invalid engine version: %q
• unsupported target: %v
• invalid loader: %q
• inject: file %q not found

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