gohugoio/hugo · error

meta init failed: %s

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.

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)

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: %s
• missing 'src' in metadata for resource
• resource %d to post process is nil
• h.ResourceSpec is nil
• alignx must be one of left, center, right

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