gohugoio/hugo · error

config needs a filename

Error message

config needs a filename

What it means

The `images.Config` function reads and decodes an image file to return its `image.Config` (dimensions, color type). After casting the argument to a string, if it is empty the function cannot locate a file and rejects the call at images.go:78–79.

Solutions

1. Pass a valid relative path: `{{ (images.Config "images/logo.png") }}`.
2. Guard with a conditional: `{{ with $path }}{{ (images.Config .) }}{{ end }}`.
3. Verify the path variable is non-empty before the call.

Example fix

// before
{{ (images.Config .MaybeEmptyPath) }}
// after
{{ with .MaybeEmptyPath }}{{ (images.Config .) }}{{ end }}

{{ with $path }}{{ (images.Config .) }}{{ end }}

func isNonEmptyString(v any) bool {
    s, ok := v.(string)
    return ok && s != ""
}

When it happens

Trigger: Calling `{{ (images.Config "") }}` or passing a template variable that resolves to an empty string, e.g. `{{ (images.Config .MissingPath) }}`.

Common situations: A front matter field or Scratch variable intended to hold an image path is unset, yielding an empty string. The developer expects a nil/zero config but gets an explicit error.

Related errors

• cannot encode an empty string
• error correction level must be one of low, medium…
• 'increment' must be > 0
• 'increment' must be < 0
• 'increment' must not be 0

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

Appendix: 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 52c9bd7908)