{"record":{"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":"exception","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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/page__ref.go#L61-L97","documentation":"Returned by pageRef.ref (page__ref.go:79) when decodeRefArgs fails to WeakDecode the arguments map into refArgs {Path, Lang, OutputFormat}. This is the .Ref / refLink path used by the ref and relref shortcodes and the .Ref method on pages.","triggerScenarios":"Passing .Ref a value that is not a map (e.g. a bare string when a map is expected in the new API); a field with the wrong type (e.g. Lang as an int); malformed arguments from a hand-written {{< ref >}} invocation.","commonSituations":"Mixing the old positional ref shortcode style with the new map style; passing `.File.Dir` (string) where `.Ref` expects a map; typos like `langs` instead of `lang` combined with a non-string value.","solutions":["Pass a properly typed map to .Ref, e.g. `.Ref (dict \"path\" \"posts/a.md\" \"lang\" \"en\")`.","When using the ref/relref shortcode, use the documented path string form: `{{< ref \"posts/a.md\" >}}`.","Ensure Lang and OutputFormat values are strings and Path is present."],"exampleFix":"{{/* before */}}\n{{ .Ref .File.Dir }}\n\n{{/* after */}}\n{{ .Ref (dict \"path\" \"posts/a.md\") }}","handlingStrategy":"validation","validationCode":null,"typeGuard":"{{/* Type-guard .Ref args before calling */}}\n{{ $args := .Params.refargs }}\n{{ if and (reflect.IsMap $args) (index $args \"path\") }}\n  {{ .Ref $args }}\n{{ else }}\n  {{ warnf \".Ref needs a map with a string 'path'\" }}\n{{ end }}","tryCatchPattern":null,"preventionTips":["Standardize on the map form (dict \"path\" \"...\") for .Ref across the project.","Keep Lang/OutputFormat values as strings; avoid passing computed non-string values.","Prefer the {{< ref \"path\" >}} shortcode for simple cases — Hugo validates its args."],"tags":["ref","templates","type-mismatch"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}