{"id":"b59778a54739047b","repo":"gohugoio/hugo","slug":"invalid-arguments-to-ref-w","errorCode":null,"errorMessage":"invalid arguments to Ref: %w","messagePattern":"invalid arguments to Ref: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/page__ref.go","lineNumber":79,"sourceCode":"\t\t\tif ss.Lang() == ra.Lang {\n\t\t\t\tfound = true\n\t\t\t\ts = ss\n\t\t\t}\n\t\t}\n\n\t\tif !found {\n\t\t\tp.p.s.siteRefLinker.logNotFound(ra.Path, fmt.Sprintf(\"no site found with lang %q\", ra.Lang), nil, text.Position{})\n\t\t\treturn ra, nil, nil\n\t\t}\n\t}\n\n\treturn ra, s, nil\n}\n\nfunc (p pageRef) ref(argsm map[string]any, source any) (string, error) {\n\targs, s, err := p.decodeRefArgs(argsm)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"invalid arguments to Ref: %w\", err)\n\t}\n\n\tif s == nil {\n\t\treturn p.p.s.siteRefLinker.notFoundURL, nil\n\t}\n\n\tif args.Path == \"\" {\n\t\treturn \"\", nil\n\t}\n\n\treturn s.siteRefLinker.refLink(args.Path, source, false, args.OutputFormat)\n}\n\nfunc (p pageRef) relRef(argsm map[string]any, source any) (string, error) {\n\targs, s, err := p.decodeRefArgs(argsm)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"invalid arguments to Ref: %w\", err)\n\t}","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/hugolib/page__ref.go#L61-L97","documentation":"The `ref`/`relref` template functions (and shortcodes) accept either a path string or an options map (path, lang, outputFormat). decodeRefArgs normalizes the input and mapstructure-decodes the map into refArgs; if that argument shape can't be interpreted at all, ref returns this error. Note the mapstructure decode error itself is swallowed at line 52 — this wrapper fires when the surrounding arg normalization fails.","triggerScenarios":"Calling `.Ref`/`.RelRef` (or the ref/relref shortcodes) with arguments that aren't a string or a map decodable to {path, lang, outputFormat} — e.g. passing a slice, a page object, or a map with values of wildly wrong types from a template like `{{ .Ref (dict \"path\" .Pages) }}`.","commonSituations":"Custom shortcodes or partials that build the ref args dict dynamically and pass a non-string value for path/lang/outputFormat; migrating old templates that passed positional args incorrectly; typos producing nested structures instead of flat maps.","solutions":["Pass either a plain string path (`{{ ref . \"about.md\" }}`) or a flat dict: `{{ .Ref (dict \"path\" \"/about\" \"lang\" \"fr\" \"outputFormat\" \"amp\") }}`.","Inspect the dynamic values you feed into the args dict — ensure path/lang/outputFormat are strings.","Check the wrapped error message for which field failed to decode and fix its type."],"exampleFix":"{{/* before */}}\n{{ .Ref (dict \"path\" .Page) }}\n\n{{/* after */}}\n{{ .Ref (dict \"path\" .Page.Path) }}","handlingStrategy":"validation","validationCode":"{{/* validate args before calling .Ref */}}\n{{ $args := dict \"path\" \"/posts/foo\" \"outputFormat\" \"html\" }}\n{{ if not (isset $args \"path\") }}{{ errorf \"Ref requires path\" }}{{ end }}","typeGuard":null,"tryCatchPattern":"{{ with try (.Ref (dict \"path\" $p)) }}\n  {{ with .Err }}{{ warnf \"bad ref %q: %s\" $p . }}{{ else }}{{ .Value }}{{ end }}\n{{ end }}","preventionTips":["Always pass Ref/RelRef a map with a string \"path\" key; other shapes fail decoding","Restrict optional keys to the documented set (path, lang, outputFormat)","Set refLinksErrorLevel and test broken refs in CI so invalid arguments surface before deploy"],"tags":["hugo","templates","ref","relref","arguments"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}