gohugoio/hugo · error

cannot encode an empty string

Error message

cannot encode an empty string

What it means

`images.QR` encodes text into a QR code PNG resource. After casting the first argument to a string, Hugo requires it to be non-empty because an empty payload produces no meaningful QR code; it fails fast instead of generating a useless image.

Source

Thrown at tpl/images/images.go:143

		Level     string // error correction level; one of low, medium, quartile, or high
		Scale     int    // number of image pixels per QR code module
		TargetDir string // target directory relative to publishDir
	}{
		Level: qrDefaultErrorCorrectionLevel,
		Scale: qrDefaultScale,
	}

	if len(args) == 0 || len(args) > 2 {
		return nil, errors.New("requires 1 or 2 arguments")
	}

	text, err := cast.ToStringE(args[0])
	if err != nil {
		return nil, err
	}

	if text == "" {
		return nil, errors.New("cannot encode an empty string")
	}

	if len(args) == 2 {
		err := mapstructure.WeakDecode(args[1], &opts)
		if err != nil {
			return nil, err
		}
	}

	level, ok := qrErrorCorrectionLevels[opts.Level]
	if !ok {
		return nil, errors.New("error correction level must be one of low, medium, quartile, or high")
	}

	if opts.Scale < 2 {
		return nil, errors.New("scale must be an integer greater than or equal to 2")
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Wrap the call in a guard: `{{ with .Params.url }}{{ $qr := images.QR . }}...{{ end }}`.
2. Ensure the source value (front matter field, site param, permalink) is populated for every page rendering the template.
3. Trace where the empty string comes from (e.g. `printf` the value with `warnf`) before calling QR.

Example fix

<!-- before -->
{{ $qr := images.QR .Params.shortlink }}
<!-- after -->
{{ with .Params.shortlink }}
  {{ $qr := images.QR . }}
  <img src="{{ $qr.RelPermalink }}">
{{ end }}

{{ $text := .Params.qrText | default "" }}
{{ if $text }}
  {{ $qr := images.QR $text }}
{{ else }}
  {{ errorf "qrText param missing on %s" .Path }}
{{ end }}

When it happens

Trigger: Calling `{{ images.QR "" }}` or `{{ images.QR $text }}` where `$text` evaluates to an empty string.

Common situations: Generating QR codes from front matter (e.g. `.Params.url`) or `.Permalink` on pages where the value is missing; templating a URL from site params that aren't set in the environment's config.

Related errors

• error correction level must be one of low, medium, quartile,
• scale must be an integer greater than or equal to 2
• config needs a filename
• must provide an image and one or more filters
• format %q not supported

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