gohugoio/hugo · error

first argument must be a map

Error message

first argument must be a map

What it means

Thrown by transform.Unmarshal when two arguments are supplied but the first is not a map[string]any (tpl/transform/unmarshal.go:49-51). In the two-argument form the first argument must be an options map (e.g. CSV delimiter/comment); the second is the data.

Source

Thrown at tpl/transform/unmarshal.go:51

)

// Unmarshal unmarshals the data given, which can be either a string, json.RawMessage
// or a Resource. Supported formats are JSON, TOML, YAML, and CSV.
// You can optionally provide an options map as the first argument.
func (ns *Namespace) Unmarshal(args ...any) (any, error) {
	if len(args) < 1 || len(args) > 2 {
		return nil, errors.New("unmarshal takes 1 or 2 arguments")
	}

	var data any
	decoder := metadecoders.Default

	if len(args) == 1 {
		data = args[0]
	} else {
		m, ok := args[0].(map[string]any)
		if !ok {
			return nil, errors.New("first argument must be a map")
		}

		var err error

		data = args[1]
		decoder, err = decodeDecoder(m)
		if err != nil {
			return nil, fmt.Errorf("failed to decode options: %w", err)
		}
	}

	if r, ok := data.(resource.UnmarshableResource); ok {
		key := r.Key()

		if key == "" {
			return nil, errors.New("no Key set in Resource")
		}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Use a map (dict) for options: {{ transform.Unmarshal (dict "delimiter" ",") .CSV }}.
2. If you have no options, pass only the data: {{ transform.Unmarshal .Data }}.

Example fix

// before
{{ transform.Unmarshal "csv" .CSVData }}
// after
{{ transform.Unmarshal (dict "delimiter" ",") .CSVData }}

{{ transform.Unmarshal (dict "delimiter" ",") .CSV }}

{{/* first arg must be map[string]any when two args given */}}
{{ if reflect.IsMap .Opts }}{{ transform.Unmarshal .Opts .Data }}{{ else }}{{ transform.Unmarshal .Data }}{{ end }}

When it happens

Trigger: Calling {{ transform.Unmarshal "csv" .Data }} (string instead of map) or {{ transform.Unmarshal .SomeString .Data }}.

Common situations: Passing the format as a plain string instead of an options map; misreading the signature; piping a string then data.

Related errors

• unmarshal takes 1 or 2 arguments
• start argument must be an integer
• length argument must be an integer
• ellipsis must be a string
• text must be a string

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