{"record":{"id":"318a5105b175d834","repo":"gohugoio/hugo","slug":"local-ref-q-not-found","errorCode":null,"errorMessage":"local ref %q not found","messagePattern":"local ref %q not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/openapi/openapi3/openapi3.go","lineNumber":194,"sourceCode":"\t\t}\n\t\tcontent, err := resources.InternalResourceSourceContent(r.ctx, res)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to read remote ref %q: %w\", loc.String(), err)\n\t\t}\n\t\tr.idm.AddIdentity(identity.FirstIdentity(res))\n\t\treturn []byte(content), nil\n\t}\n\n\tvar filename string\n\tif strings.HasPrefix(loc.Path, \"/\") {\n\t\tfilename = loc.Path\n\t} else {\n\t\tfilename = path.Join(r.relBase, loc.Path)\n\t}\n\n\tres := r.ns.resourcesNs.Get(filename)\n\tif res == nil {\n\t\treturn nil, fmt.Errorf(\"local ref %q not found\", loc.String())\n\t}\n\tcontent, err := resources.InternalResourceSourceContent(r.ctx, res)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read local ref %q: %w\", loc.String(), err)\n\t}\n\tr.idm.AddIdentity(identity.FirstIdentity(res))\n\treturn []byte(content), nil\n}\n","sourceCodeStart":176,"sourceCodeEnd":203,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/tpl/openapi/openapi3/openapi3.go#L176-L203","documentation":"A local $ref (no scheme/host) resolves to a filename that resourcesNs.Get cannot locate in the assets/resources pipeline, so Get returns nil. See openapi3.go:192-195.","triggerScenarios":"$ref: schemas/user.yaml but the file is not under the assets mount or not relative to the OpenAPI document's directory.","commonSituations":"Relative path resolved from an unexpected base directory; file not added to Hugo module/file mounts; case-sensitivity mismatch on a case-sensitive filesystem.","solutions":["Ensure the referenced file exists under the assets or resources mount.","Check that the path is relative to the OpenAPI document's directory (relBase).","Verify Hugo module/file mounts (mounts in config) include the referenced file.","Watch for case-sensitivity mismatches between dev (macOS/Windows) and deploy (Linux)."],"exampleFix":"// before (wrong relative path)\n$ref: user.yaml\n\n// after (correct relative path from spec dir)\n$ref: schemas/user.yaml","handlingStrategy":"validation","validationCode":"// Verify the local file resolves in the assets pipeline before parsing refs.\nres := ns.resourcesNs.Get(filename)\nif res == nil {\n    return fmt.Errorf(\"local ref %q not found; check assets mounts\", filename)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure referenced local files are present under the assets/resources mount.","Resolve $ref paths relative to the OpenAPI document's directory.","Beware case-sensitivity differences between dev and deploy environments."],"tags":["hugo","openapi","resource","ref","filesystem"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}