gohugoio/hugo · error

failed to load image config: %w

Error message

failed to load image config: %w

What it means

Hugo panics with this error in Image.initConfig when it lazily decodes an image's header (dimensions/format) via Codec.DecodeConfig and the read or decode fails. The config is loaded on first access to properties like .Width/.Height, so a corrupt or unreadable image surfaces here rather than at resource-open time. The wrapped error carries the underlying cause (I/O error or malformed image data).

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 8a468df065)

Solutions

1. Identify the offending image from the surrounding error context and verify it opens in an image viewer or with `file <path>` — replace it if corrupt.
2. If using Git LFS, run `git lfs pull` so real binaries, not pointer stubs, are present in CI.
3. Ensure the file's actual format matches one Hugo can decode (jpeg, png, gif, tiff, bmp, webp, avif); re-export from your editor if not.
4. Guard templates against non-image resources before calling image methods: `{{ with .Resources.GetMatch "cover.*" }}{{ if eq .ResourceType "image" }}...{{ end }}{{ end }}`.

Example fix

// before: LFS pointer stub committed instead of binary
// assets/img/hero.jpg -> "version https://git-lfs.github.com/spec/v1..."
$ git lfs pull
// after: real JPEG bytes present, {{ $img.Width }} works

// Verify the file decodes as an image before processing
f, err := os.Open(path)
if err != nil { return err }
defer f.Close()
if _, _, err := image.DecodeConfig(f); err != nil {
    return fmt.Errorf("invalid or unsupported image %q: %w", path, err)
}

if err != nil && strings.Contains(err.Error(), "failed to load image config") {
    // corrupt/truncated file or unregistered format — skip or report the asset
}

When it happens

Trigger: Calling .Width, .Height, or an image processing method (.Resize, .Fit, etc.) in a template on an image resource whose bytes cannot be decoded — truncated file, wrong magic bytes for its extension, unsupported/corrupt encoding — or whose ReadSeekCloser fails to open.

Common situations: Corrupted images committed to assets/ or static/; files with an image extension that are actually HTML (e.g. a saved 404 page from a broken download); Git LFS pointer files not pulled so the 'image' is a tiny text stub; SVG or unsupported formats renamed with .png/.jpg extensions.

Related errors

• failed to decode gif: %w
• failed to decode config for language %q: %w
• failed to decode %q: %w
• local ref %q not found
• config needs a filename

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