gohugoio/hugo · error

can't extract relative path, unknown prefix

Error message

can't extract relative path, unknown prefix

What it means

makePathRelative strips one of a set of known base directories (content mounts, etc.) from an absolute path to get the path relative to that root. If the input path doesn't start with any of the candidate directories, Hugo cannot determine which root it belongs to and returns this error along with the unmodified path.

Source

Thrown at common/paths/path.go:266

	// Check for the most likely first (faster).
	isAllowed := unicode.IsLetter(r) || unicode.IsDigit(r)
	isAllowed = isAllowed || r == '.' || r == '/' || r == '\\' || r == '_' || r == '#' || r == '+' || r == '~' || r == '-' || r == '@'
	isAllowed = isAllowed || unicode.IsMark(r)
	isAllowed = isAllowed || (r == '%' && i+2 < len(s) && ishex(s[i+1]) && ishex(s[i+2]))
	return isAllowed
}

// From https://golang.org/src/net/url/url.go
func ishex(c byte) bool {
	switch {
	case '0' <= c && c <= '9':
		return true
	case 'a' <= c && c <= 'f':
		return true
	case 'A' <= c && c <= 'F':
		return true
	}
	return false
}

var slashFunc = func(r rune) bool {
	return r == '/'
}

// Dir behaves like path.Dir without the path.Clean step.
//
//	The returned path ends in a slash only if it is the root "/".
func Dir(s string) string {
	dir, _ := path.Split(s)
	if len(dir) > 1 && dir[len(dir)-1] == '/' {
		return dir[:len(dir)-1]
	}
	return dir
}

// FieldsSlash cuts s into fields separated with '/'.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check that contentDir and module mounts point at the actual (resolved) directories containing your files; avoid symlinks that escape the project root.
2. On Windows, ensure consistent casing/drive letters in config paths.
3. Run hugo from the site root, or pass --source with the correct project path.
4. If reproducible with plain config, file a Hugo issue including the offending file path.

if !strings.HasPrefix(filepath.Clean(path), filepath.Clean(basePath)) {
    return fmt.Errorf("%s is outside %s", path, basePath)
}

When it happens

Trigger: A source file path passed to makePathRelative that has no prefix matching any of the possibleDirectories candidates — e.g. a file resolved outside all configured content directories/module mounts, or path-separator/casing mismatches between the file path and the configured roots.

Common situations: Symlinked content directories where the resolved absolute path differs from the configured contentDir; Hugo Modules mounts pointing outside the project; case-differing drive letters or mixed slashes on Windows; running hugo from an unexpected working directory with relative contentDir settings.

Related errors

• failed to vendor module: %w
• failed to copy module to vendor dir: %w
• failed to make target dir: %w
• failed to copy module file to vendor: %w
• failed to copy resources to vendor dir: %w

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/5855d5688205cf4f.json. Report an issue: GitHub ↗.