gohugoio/hugo · error

format %q not supported

Error message

format %q not supported

What it means

Codec.Encode switches on the target image format (JPEG, PNG, GIF, TIFF, BMP, AVIF, WEBP); an unrecognized conf.TargetFormat falls through to this error. It is a guard for an unsupported output format reaching the encoder — normally the format string in an image-processing spec is validated earlier, so this indicates an unsupported conversion target.

Source

Thrown at resources/images/codec.go:165

			"hint":         conf.Hint,
		}
		return d.avif.Encode(w, img, opts)
	case WEBP:
		// Convert bool to int because the C code reads it as a number.
		useSharpYuvInt := 0
		if conf.UseSharpYuv {
			useSharpYuvInt = 1
		}
		opts := map[string]any{
			"compression": conf.Compression,
			"quality":     conf.Quality,
			"hint":        conf.Hint,
			"useSharpYuv": useSharpYuvInt,
			"method":      conf.Method,
		}
		return d.webp.Encode(w, img, opts)
	default:
		return fmt.Errorf("format %q not supported", conf.TargetFormat)
	}
}

func (d *Codec) DecodeFormat(f Format, r io.Reader) (image.Image, error) {
	d.debugl.Log(
		logg.StringFunc(
			func() string {
				return fmt.Sprintf("Decoding image from format %s", f)
			},
		),
	)
	switch f {
	case JPEG, PNG:
		// We reworked this decode/encode setup to get full WebP support in v0.153.0.
		// In the first take of that we used f to decide whether to call png.Decode or jpeg.Decode here,
		// but testing it on some sites, it seems that it's not uncommon to store JPEGs with PNG extensions and vice versa.
		// So, to reduce some noise in that release, we fallback to the standard library here,
		// which will read the magic bytes and decode accordingly.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Use a supported target format in the processing spec: jpg, png, gif, tiff, bmp, webp, or avif (e.g. `.Resize "600x webp"`).
2. Upgrade Hugo if the theme requests webp/avif and your version predates their encoder support.
3. Check the theme's image partials for the format token being passed and correct any typo.

Example fix

// before
{{ $img := $img.Resize "600x heic" }}
// after
{{ $img := $img.Resize "600x webp" }}

var encodable = map[string]bool{"jpg": true, "jpeg": true, "png": true, "gif": true, "tif": true, "tiff": true, "bmp": true, "webp": true}
if !encodable[strings.TrimPrefix(strings.ToLower(ext), ".")] {
    return fmt.Errorf("cannot encode to %q", ext)
}

When it happens

Trigger: An image operation whose options request a target format outside the supported set — e.g. an unsupported format token in `.Process`/`.Resize` option strings, or internal Format values not wired to an encoder.

Common situations: Asking Hugo to output SVG, HEIC, or another format it can't encode; typos in the format token of a processing spec; older Hugo versions lacking a newer format (webp/avif) that a theme's templates request.

Related errors

• format %q not supported
• config needs a filename
• must provide an image and one or more filters
• cannot encode an empty string
• error correction level must be one of low, medium, quartile,

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