gohugoio/hugo · error

failed to get remote ref

Error message

failed to get remote ref %q: %w

What it means

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.

Solutions

1. Verify the remote URL is reachable from the build environment (curl it manually).
2. Provide GetRemote options (headers, method, credentials) when auth is required.
3. Vendor the remote spec locally and switch to a local $ref to remove the network dependency.
4. Retry on transient network failures or enable caching.

Example fix

// before (remote ref in spec)
$ref: https://api.example.com/schemas/user.yaml

// after (vendored local ref)
$ref: schemas/user.yaml

// Pre-check remote reachability / validate the URL shape before building.
u, err := url.Parse(loc.String())
if err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid remote ref %q", loc.String())
}

res, err := ns.resourcesNs.GetRemote(loc.String(), opts.GetRemote)
if err != nil {
    // transient? retry with backoff; permanent? surface wrapped err
    return fmt.Errorf("failed to get remote ref %q: %w", loc.String(), err)
}

When it happens

Trigger: A spec references https://example.com/schemas/user.yaml and the host is unreachable, returns a non-200 status, or the request times out.

Common situations: CI/build environment without network egress; a typo in the ref URL; the remote requires authentication headers; intermittent network failures.

Related errors

• failed to read remote ref
• local ref not found
• failed to clone
• failed to fetch remote resource from
• failed to parse URL for resource

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/86a564fe6a8946a5. Report an issue: GitHub.

Appendix: source

Thrown at tpl/openapi/openapi3/openapi3.go:175

	return v, nil
}

type refResolver struct {
	ctx     context.Context
	idm     identity.Manager
	opts    unmarshalOptions
	relBase string
	ns      *Namespace
}

// resolveExternalRef resolves external references in OpenAPI documents by either fetching
// remote URLs or loading local files from the assets directory, depending on the reference location.
func (r *refResolver) resolveExternalRef(loader *kopenapi3.Loader, loc *url.URL) ([]byte, error) {
	if loc.Scheme != "" && loc.Host != "" {
		res, err := r.ns.resourcesNs.GetRemote(loc.String(), r.opts.GetRemote)
		if err != nil {
			return nil, fmt.Errorf("failed to get remote ref %q: %w", loc.String(), err)
		}
		content, err := resources.InternalResourceSourceContent(r.ctx, res)
		if err != nil {
			return nil, fmt.Errorf("failed to read remote ref %q: %w", loc.String(), err)
		}
		r.idm.AddIdentity(identity.FirstIdentity(res))
		return []byte(content), nil
	}

	var filename string
	if strings.HasPrefix(loc.Path, "/") {
		filename = loc.Path
	} else {
		filename = path.Join(r.relBase, loc.Path)
	}

	res := r.ns.resourcesNs.Get(filename)
	if res == nil {

View on GitHub (pinned to 52c9bd7908)