gohugoio/hugo · critical

failed to load image config

Error message

failed to load image config: %w

What it means

A panic (not a returned error) raised by Image.initConfig() when the image codec's DecodeConfig fails — meaning Hugo could not read the image's dimensions or format header. The panic fires lazily on first access to the image config (via sync.Once), and is NOT recovered within this function, so it will crash the build unless caught upstream.

Solutions

  1. Identify which image file triggered the panic from the build output or stack trace, then open the file in an image viewer to confirm it is corrupt.
  2. Re-export or re-save the image from the original source, or replace it with a known-good copy.
  3. Verify the file extension matches the actual format (e.g. a WEBP file renamed to .png).
  4. Run 'file path/to/image.jpg' or 'identify path/to/image.jpg' (ImageMagick) to confirm the file is a valid image of the expected type.

Example fix

# The error is in an image asset, not code.
# Verify the file integrity:
# before: corrupt or truncated file at assets/images/hero.jpg
# after: re-export from source and replace the file

# Quick check from shell:
# file assets/images/hero.jpg
# identify assets/images/hero.jpg
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate image files before Hugo processes them.
// In Go, if using Hugo as a library, decode the config yourself first:
func checkImageDecodable(codec Codec, format Format, r io.Reader) error {
    _, _, err := codec.DecodeConfig(format, r)
    return err
}

// From the shell, validate all images before building:
// find assets/ static/ -type f \( -name '*.jpg' -o -name '*.png' -o -name '*.webp' \) -exec identify {} \; >/dev/null

Try / catch

// If using Hugo as a Go library, wrap image processing in a recover
defer func() {
    if r := recover(); r != nil {
        log.Printf("image processing panicked (likely corrupt image): %v", r)
        // fall back to a placeholder or skip the image
    }
}()
img.initConfig() // may panic on corrupt images

Prevention

When it happens

Trigger: Hugo encounters a corrupt, truncated, or zero-byte image file when it needs to read the image dimensions (e.g. for responsive image markup, resizing, or layout). The panic occurs at image.go:121 inside initConfig, triggered when configLoaded is false and DecodeConfig returns an error.

Common situations: A partially downloaded or uploaded image asset; a file with a correct extension (.jpg, .png) but wrong or corrupt content; a CI environment where an image asset was not checked in or was corrupted by Git LFS; switching image processing libraries or Hugo versions that change supported formats.

Related errors

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/71b4a0e046cc4868. Report an issue: GitHub.

Appendix: source

Thrown at resources/images/image.go:121

	var err error
	i.configInit.Do(func() {
		if i.configLoaded {
			return
		}

		var f hugio.ReadSeekCloser

		f, err = i.Spec.ReadSeekCloser()
		if err != nil {
			return
		}
		defer f.Close()

		i.config, _, err = i.Proc.Codec.DecodeConfig(i.Format, f)
	})

	if err != nil {
		panic(fmt.Errorf("failed to load image config: %w", err))
	}
}

func NewImageProcessor(debugl, warnl logg.LevelLogger, wasmDispatchers *warpc.Dispatchers, cfg *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal]) (*ImageProcessor, error) {
	e := cfg.Config.Imaging.Exif
	exifDecoder, err := meta.NewDecoder(
		meta.WithDateDisabled(e.DisableDate),
		meta.WithLatLongDisabled(e.DisableLatLong),
		meta.ExcludeFields(e.ExcludeFields),
		meta.IncludeFields(e.IncludeFields),
		meta.WithWarnLogger(warnl),
	)
	if err != nil {
		return nil, err
	}

	m := cfg.Config.Imaging.Meta
	metaDecoder, err := meta.NewDecoder(

View on GitHub (pinned to 52c9bd7908)