{"id":"bea81f40e269fbbc","repo":"gohugoio/hugo","slug":"invalid-number-of-arguments-to-ref","errorCode":null,"errorMessage":"invalid number of arguments to ref","messagePattern":"invalid number of arguments to ref","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/urls/urls.go","lineNumber":143,"sourceCode":"\t)\n\n\tv := args\n\tif _, ok := v.([]any); ok {\n\t\tv = cast.ToStringSlice(v)\n\t}\n\n\tswitch v := v.(type) {\n\tcase map[string]any:\n\t\treturn v, nil\n\tcase map[string]string:\n\t\tm := make(map[string]any)\n\t\tfor k, v := range v {\n\t\t\tm[k] = v\n\t\t}\n\t\treturn m, nil\n\tcase []string:\n\t\tif len(v) == 0 || len(v) > 2 {\n\t\t\treturn nil, fmt.Errorf(\"invalid number of arguments to ref\")\n\t\t}\n\t\t// These were the options before we introduced the map type:\n\t\ts = v[0]\n\t\tif len(v) == 2 {\n\t\t\tof = v[1]\n\t\t}\n\tdefault:\n\t\tvar err error\n\t\ts, err = cast.ToStringE(args)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t}\n\n\treturn map[string]any{\n\t\t\"path\":         s,\n\t\t\"outputFormat\": of,","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/urls/urls.go#L125-L161","documentation":"Hugo's `ref`/`relref` template functions accept either a page path string, a map of options, or a legacy string slice of 1–2 elements (path and optional output format). This error is raised in `refArgsToMap` when the arguments are passed as a slice that is empty or has more than two elements, so Hugo cannot map them to a path and output format.","triggerScenarios":"Calling `{{ ref . (slice) }}` or `{{ ref . (slice \"about\" \"html\" \"extra\") }}` — i.e. passing a `[]string`/`[]any` with 0 or 3+ elements to `ref`, `relref`, or the corresponding page methods `.Ref`/`.RelRef`.","commonSituations":"Templates written for the old two-argument slice form that accidentally append extra values; building the argument slice dynamically from front matter and it comes out empty; confusing the slice form with the newer options-map form.","solutions":["Pass a plain string: `{{ ref . \"/blog/my-post.md\" }}`.","If you need an output format, use exactly two slice elements: `{{ ref . (slice \"my-post\" \"amp\") }}`.","Prefer the map form for options: `{{ ref . (dict \"path\" \"my-post\" \"outputFormat\" \"amp\") }}`.","If the slice is built dynamically, guard against it being empty before calling ref."],"exampleFix":"<!-- before -->\n{{ ref . (slice \"my-post\" \"amp\" \"en\") }}\n<!-- after -->\n{{ ref . (dict \"path\" \"my-post\" \"outputFormat\" \"amp\" \"lang\" \"en\") }}","handlingStrategy":"validation","validationCode":"{{/* ref takes the page plus one options/path argument — build args explicitly */}}\n{{ $path := \"/docs/install.md\" }}\n{{ with $path }}{{ ref $ . }}{{ end }}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Call ref/relref with exactly two args: the page context and a path (or options map) — e.g. {{ ref . \"about.md\" }}","When passing an options map, use dict: {{ ref . (dict \"path\" \"about.md\" \"lang\" \"fr\") }}","Prefer .GetPage plus .RelPermalink when you need graceful handling of missing pages"],"tags":["hugo","templates","ref","arguments"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}