{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/openapi/openapi3/openapi3.go#L157-L193","documentation":"When resolving external `$ref`s in an OpenAPI document, refs with a scheme and host are fetched with `resources.GetRemote` (tpl/openapi/openapi3/openapi3.go:175). If that fetch fails — network error, non-2xx status, timeout, or blocked by Hugo's HTTP security policy — the resolver wraps the underlying error with the ref URL in this message.","triggerScenarios":"Unmarshalling a spec containing `$ref: \"https://example.com/schemas/foo.yaml\"` where the remote host is unreachable, returns 404/403/5xx, requires auth headers not supplied via the `getRemote` options, or is disallowed by `security.http.urls` in the Hugo config.","commonSituations":"CI environments without outbound network access, expired or moved schema URLs, missing auth headers for private schema registries, Hugo's security allowlist not including the ref's domain, and proxy/TLS issues.","solutions":["Check the wrapped error: fix the URL, network access, or the remote server's response.","Pass required headers/options via the options map: `{{ openapi3.Unmarshal $r (dict \"getRemote\" (dict \"headers\" (dict \"Authorization\" ...))) }}` (keep tokens in env config, not templates).","Allow the domain in your Hugo config `security.http.urls` if the fetch is being blocked.","Vendor the referenced schema into `assets/` and change the `$ref` to a local path so no network is needed at build time."],"exampleFix":"# before: build depends on unreachable remote $ref\n$ref: \"https://schemas.example.com/pet.yaml\"\n# after: vendored locally under assets/\n$ref: \"./schemas/pet.yaml\"","handlingStrategy":"retry","validationCode":"# pre-flight the remote $ref targets referenced by the spec\ncurl -sfI https://example.com/schemas/user.yaml >/dev/null || echo \"unreachable ref\"","typeGuard":null,"tryCatchPattern":"{{/* build-time: remote $ref fetch failures surface as build errors; use try where available */}}\n{{ $r := try (openapi3.Unmarshal $spec) }}\n{{ with $r.Err }}{{ warnf \"openapi remote ref failed: %s\" . }}{{ else }}{{ $doc := $r.Value }}{{ end }}","preventionTips":["Vendor remote $refs locally when possible so builds don't depend on external hosts","Verify remote ref URLs are reachable in CI before the Hugo build","Treat transient network failures as retryable at the CI level (re-run the build), not by looping in templates","Pin remote spec URLs to versioned/immutable paths so refs don't 404 after upstream changes"],"tags":["hugo","openapi","network","remote-ref"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}