{"record":{"id":"3ac6117d5865eb2c","repo":"gohugoio/hugo","slug":"failed-to-read-remote-ref-q-w","errorCode":null,"errorMessage":"failed to read remote ref %q: %w","messagePattern":"failed to read remote ref %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/openapi/openapi3/openapi3.go","lineNumber":179,"sourceCode":"type refResolver struct {\n\tctx     context.Context\n\tidm     identity.Manager\n\topts    unmarshalOptions\n\trelBase string\n\tns      *Namespace\n}\n\n// resolveExternalRef resolves external references in OpenAPI documents by either fetching\n// remote URLs or loading local files from the assets directory, depending on the reference location.\nfunc (r *refResolver) resolveExternalRef(loader *kopenapi3.Loader, loc *url.URL) ([]byte, error) {\n\tif loc.Scheme != \"\" && loc.Host != \"\" {\n\t\tres, err := r.ns.resourcesNs.GetRemote(loc.String(), r.opts.GetRemote)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to get remote ref %q: %w\", loc.String(), err)\n\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 {","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/tpl/openapi/openapi3/openapi3.go#L161-L197","documentation":"The remote $ref was successfully fetched but reading its body via resources.InternalResourceSourceContent failed. The wrapped error (%w) describes the read failure. See openapi3.go:177-180.","triggerScenarios":"The remote returned a 200 with a non-text body, an HTML error page, or a content type that cannot be extracted into source content.","commonSituations":"Remote returned an HTML error page with HTTP 200; gzip/compression handling issues; resource content type mismatch after a redirect.","solutions":["Inspect the wrapped error to identify the specific read/extraction failure.","Verify the remote endpoint returns plain YAML or JSON content (not HTML or binary).","Check the HTTP status and Content-Type header of the actual response.","Vendor the spec locally if the remote content shape is unreliable."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Validate the fetched resource has readable text content before resolving.\nif res == nil { return errors.New(\"remote resource is nil\") }","typeGuard":null,"tryCatchPattern":"content, err := resources.InternalResourceSourceContent(ctx, res)\nif err != nil {\n    return fmt.Errorf(\"failed to read remote ref %q: %w\", loc.String(), err)\n}","preventionTips":["Confirm the remote endpoint returns plain YAML/JSON, not HTML or binary.","Inspect the wrapped error to distinguish HTTP, decompression, or content-type failures."],"tags":["hugo","openapi","network","remote","ref","io"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}