gohugoio/hugo · error

config needs a filename

Error message

config needs a filename

What it means

`images.Config` reads the dimensions of an image file at a path relative to the working directory. After casting the argument to a string, Hugo checks it is non-empty; an empty filename cannot be opened, so it fails fast with this error rather than passing an empty path to the filesystem.

Source

Thrown at tpl/images/images.go:79

// Namespace provides template functions for the "images" namespace.
type Namespace struct {
	*images.Filters
	readFileFs   afero.Fs
	cache        *maphelpers.ConcurrentMap[string, image.Config]
	deps         *deps.Deps
	createClient *create.Client
}

// Config returns the image.Config for the specified path relative to the
// working directory.
func (ns *Namespace) Config(path any) (image.Config, error) {
	filename, err := cast.ToStringE(path)
	if err != nil {
		return image.Config{}, err
	}

	if filename == "" {
		return image.Config{}, errors.New("config needs a filename")
	}

	return ns.cache.GetOrCreate(filename, func() (image.Config, error) {
		f, err := ns.readFileFs.Open(filename)
		if err != nil {
			return image.Config{}, err
		}
		defer f.Close()

		ext := filepath.Ext(filename)
		format, _ := images.ImageFormatFromExt(ext)

		config, _, err := ns.deps.ResourceSpec.Imaging.Codec.DecodeConfig(format, f)
		return config, err
	})
}

// Filter applies the given filters to the image given as the last element in args.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Guard the call: `{{ with .Params.image }}{{ $cfg := imageConfig . }}...{{ end }}`.
2. Verify the front matter or data source actually sets the image path on every page using the template.
3. Prefer page/global resources (`.Resources.Get` / `resources.Get`) and `.Width`/`.Height`, which handle missing files more idiomatically.

Example fix

<!-- before -->
{{ $cfg := imageConfig .Params.image }}
<!-- after -->
{{ with .Params.image }}
  {{ $cfg := imageConfig . }}
  {{ $cfg.Width }}x{{ $cfg.Height }}
{{ end }}

{{ $file := "config.json" }}
{{ if $file }}{{ $cfg := images.Config (printf "exif/%s" $file) }}{{ end }}

When it happens

Trigger: Calling `{{ images.Config "" }}` or `{{ imageConfig $path }}` where `$path` evaluates to an empty string (e.g. a missing front matter field or unset variable).

Common situations: Front matter field like `.Params.image` missing on some pages while the template unconditionally calls `imageConfig`; a `default` fallback that resolves to empty; typoed variable names that silently evaluate empty.

Related errors

• must provide an image and one or more filters
• cannot encode an empty string
• error correction level must be one of low, medium, quartile,
• scale must be an integer greater than or equal to 2
• format %q not supported

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