gohugoio/hugo · error

local ref not found

Error message

local ref %q not found

What it means

A local $ref (no scheme/host) resolves to a filename that resourcesNs.Get cannot locate in the assets/resources pipeline, so Get returns nil. See openapi3.go:192-195.

Solutions

1. Ensure the referenced file exists under the assets or resources mount.
2. Check that the path is relative to the OpenAPI document's directory (relBase).
3. Verify Hugo module/file mounts (mounts in config) include the referenced file.
4. Watch for case-sensitivity mismatches between dev (macOS/Windows) and deploy (Linux).

Example fix

// before (wrong relative path)
$ref: user.yaml

// after (correct relative path from spec dir)
$ref: schemas/user.yaml

// Verify the local file resolves in the assets pipeline before parsing refs.
res := ns.resourcesNs.Get(filename)
if res == nil {
    return fmt.Errorf("local ref %q not found; check assets mounts", filename)
}

When it happens

Trigger: $ref: schemas/user.yaml but the file is not under the assets mount or not relative to the OpenAPI document's directory.

Common situations: Relative path resolved from an unexpected base directory; file not added to Hugo module/file mounts; case-sensitivity mismatch on a case-sensitive filesystem.

Related errors

• failed to get remote ref
• failed to read remote ref
• MIME not supported
• no Key set in Resource
• abort: jekyll root contains neither posts nor drafts

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

Appendix: source

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

		}
		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 {
		return nil, fmt.Errorf("failed to read local ref %q: %w", loc.String(), err)
	}
	r.idm.AddIdentity(identity.FirstIdentity(res))
	return []byte(content), nil
}

View on GitHub (pinned to 52c9bd7908)