{"record":{"id":"86a564fe6a8946a5","repo":"gohugoio/hugo","slug":"failed-to-get-remote-ref-q-w","errorCode":null,"errorMessage":"failed to get remote ref %q: %w","messagePattern":"failed to get remote ref %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/openapi/openapi3/openapi3.go","lineNumber":175,"sourceCode":"\n\treturn v, nil\n}\n\ntype 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 {","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/tpl/openapi/openapi3/openapi3.go#L157-L193","documentation":"An OpenAPI document contains a remote $ref (a URL with scheme and host); the resolver calls resourcesNs.GetRemote which failed. The wrapped error (%w) carries the network/HTTP cause. See openapi3.go:172-176.","triggerScenarios":"A spec references https://example.com/schemas/user.yaml and the host is unreachable, returns a non-200 status, or the request times out.","commonSituations":"CI/build environment without network egress; a typo in the ref URL; the remote requires authentication headers; intermittent network failures.","solutions":["Verify the remote URL is reachable from the build environment (curl it manually).","Provide GetRemote options (headers, method, credentials) when auth is required.","Vendor the remote spec locally and switch to a local $ref to remove the network dependency.","Retry on transient network failures or enable caching."],"exampleFix":"// before (remote ref in spec)\n$ref: https://api.example.com/schemas/user.yaml\n\n// after (vendored local ref)\n$ref: schemas/user.yaml","handlingStrategy":"retry","validationCode":"// Pre-check remote reachability / validate the URL shape before building.\nu, err := url.Parse(loc.String())\nif err != nil || u.Scheme == \"\" || u.Host == \"\" {\n    return fmt.Errorf(\"invalid remote ref %q\", loc.String())\n}","typeGuard":null,"tryCatchPattern":"res, err := ns.resourcesNs.GetRemote(loc.String(), opts.GetRemote)\nif err != nil {\n    // transient? retry with backoff; permanent? surface wrapped err\n    return fmt.Errorf(\"failed to get remote ref %q: %w\", loc.String(), err)\n}","preventionTips":["Vendor external specs locally to remove network dependency in CI.","Provide GetRemote options with auth headers when the endpoint requires them.","Validate ref URLs at spec-authoring time."],"tags":["hugo","openapi","network","remote","ref"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}