gohugoio/hugo · error

meta init failed

Error message

meta init failed: %s

What it means

Panic in imageResource.Meta() when the lazily-initialized metaInfoFn() returns an error. Hugo decodes general image metadata (dimensions, format) via Imaging.DecodeMeta and caches it; a decode failure or cache I/O error surfaces here as a panic. The underlying error message is included.

Solutions

1. Verify the image file is valid and openable before calling .Meta (decode it locally).
2. Fix cache directory permissions / free disk space for resources/_gen.
3. Re-save the image in a supported format (JPEG, PNG, GIF, TIFF, WebP, BMP).
4. Rename files to match their true format.

Example fix

{{/* before: .Meta panics on a corrupt image */}}
{{ with $img.Meta }}{{ .Width }}{{ end }}

{{/* after: validate the resource decodes; repair or remove the bad file */}}
{{ $img := resources.Get "banner.png" }}
{{ if and $img (ne $img.MediaType.SubType "") }}
  {{ with $img.Meta }}{{ .Width }}x{{ .Height }}{{ end }}
{{ end }}

// Validate the image decodes before calling .Meta.
// Template: guard with {{ if $img }} and known media type.
// Go: open and sniff the header to confirm format matches the extension.

// Meta panics on decode failure; recover to degrade gracefully:
func safeMeta(img *resources.ImageResource) (m *meta.MetaInfo, err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("image meta decode failed: %v", r)
        }
    }()
    return img.Meta(), nil
}

When it happens

Trigger: Calling .Meta on an image resource that cannot be decoded (corrupt headers, truncated file, unsupported format), or when the metadata cache read/write fails. DecodeMeta returns an error for images it cannot parse.

Common situations: A truncated or zero-byte image in assets/images. An unsupported/obscure image format. Cache directory permissions or disk-full conditions. A file with a wrong extension (e.g. .png that is actually a JPEG sometimes mis-decoded).

Related errors

• exif init failed
• alignx must be one of left, center, right
• h.ResourceSpec is nil
• missing 'src' in metadata for resource
• resource to post process is nil

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

Appendix: source

Thrown at resources/image.go:193

		for j, c := range colors {
			result[j] = images.ColorGoToColor(c)
		}
		return result, nil
	})
}

func (i *imageResource) Exif() *meta.ExifInfo {
	x, err := i.root.exifInfoFn()
	if err != nil {
		panic(fmt.Sprintf("exif init failed: %s", err))
	}
	return x
}

func (i *imageResource) Meta() *meta.MetaInfo {
	m, err := i.root.metaInfoFn()
	if err != nil {
		panic(fmt.Sprintf("meta init failed: %s", err))
	}
	return m
}

func (i *imageResource) getImageMetaInfoCacheTargetPath() string {
	// Increment to invalidate the meta cache
	const imageMetaInfoVersionNumber = 1

	cfgHash := i.getSpec().Imaging.Cfg.SourceHash
	df := i.getResourcePaths()
	p1, _ := paths.FileAndExt(df.File)
	h := i.hash()
	idStr := hashing.HashStringHex(h, i.size(), imageMetaInfoVersionNumber, cfgHash)
	df.File = fmt.Sprintf("%s_%s_meta.json", p1, idStr)
	return df.TargetPath()
}

// Colors returns a slice of the most dominant colors in an image

View on GitHub (pinned to 52c9bd7908)