gohugoio/hugo · error

failed to read remote ref %q: %w

Error message

failed to read remote ref %q: %w

What it means

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.

Source

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

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 {
		return nil, fmt.Errorf("local ref %q not found", loc.String())
	}
	content, err := resources.InternalResourceSourceContent(r.ctx, res)
	if err != nil {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Inspect the wrapped error to identify the specific read/extraction failure.
2. Verify the remote endpoint returns plain YAML or JSON content (not HTML or binary).
3. Check the HTTP status and Content-Type header of the actual response.
4. Vendor the spec locally if the remote content shape is unreliable.

// Validate the fetched resource has readable text content before resolving.
if res == nil { return errors.New("remote resource is nil") }

content, err := resources.InternalResourceSourceContent(ctx, res)
if err != nil {
    return fmt.Errorf("failed to read remote ref %q: %w", loc.String(), err)
}

When it happens

Trigger: 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.

Common situations: Remote returned an HTML error page with HTTP 200; gzip/compression handling issues; resource content type mismatch after a redirect.

Related errors

• failed to get remote ref %q: %w
• failed to read remote resource %q: %w
• local ref %q not found
• must provide a Resource and optionally an options map
• no Key set in Resource

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