gohugoio/hugo · error

failed to map git repo for module

Error message

failed to map git repo for module %s: %v

What it means

Wraps a failure of mapModuleRepo() for a given module after its clone exists. mapModuleRepo opens the cloned repo at a revision via gitmap; the %s is the module path, %v the mapping error (e.g. revision not found, git command failure).

Solutions

1. Inspect the wrapped %v — usually a 'reference not found' or git command failure naming the revision.
2. Re-fetch the module: `hugo mod clean` / remove the module + gitinfo cache and rebuild so the latest revision is used.
3. Confirm the module's origin hash is reachable (git ls-remote <origin>) in a blobless clone context.
4. Update the module to a commit hash that exists on the remote.

Example fix

// before: module pinned to a deleted commit
[[imports]]
path = "github.com/foo/bar"
// hugo.mod pins hash abc123 (force-pushed away)

// after: bump to an existing commit
hugo mod get github.com/foo/bar@latest

// Pre-check: confirm the referenced revision exists via ls-remote before mapping.
if out, err := exec.Command("git","ls-remote",originURL,hash).Output(); err != nil || len(out)==0 { return errors.New("revision unreachable") }

repo, err := mapModuleRepo(cfg, cloneDir, hash)
if err != nil {
    // refresh module to latest reachable revision, then retry once
    _ = hugoModGet(mod.Path()+"@latest")
    repo, err = mapModuleRepo(cfg, cloneDir, newHash)
}

When it happens

Trigger: Raised at gitinfo.go:176 when mapModuleRepo(cfg, cloneDir, origin.Hash) errors — the clone succeeded but resolving the requested revision/hash failed, or the gitmap helper command could not run.

Common situations: The module origin's recorded hash was force-pushed away (revision no longer exists in the clone); a shallow/blobless clone missing the referenced commit; gitmap unable to run git due to PATH/exec issues; submodule revision mismatch.

Related errors

• failed to clone
• git clone
• git clone
• could not determine content directory for
• must not be run from the file system root

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

Appendix: source

Thrown at hugolib/gitinfo.go:176

}

func (g *gitInfo) loadModuleRepos(cfg gitInfoConfig) error {
	for _, mod := range cfg.Modules {
		if !isGitModule(mod) {
			continue
		}

		loadGitInfo := sync.OnceValues(func() (*gitmap.GitRepo, error) {
			origin := mod.Origin()

			cloneDir, err := ensureClone(cfg, origin)
			if err != nil {
				return nil, fmt.Errorf("failed to clone %s: %v", origin.URL, err)
			}

			repo, err := mapModuleRepo(cfg, cloneDir, origin.Hash)
			if err != nil {
				return nil, fmt.Errorf("failed to map git repo for module %s: %v", mod.Path(), err)
			}
			return repo, nil
		})

		g.moduleRepoLoaders[mod.Dir()] = loadGitInfo
	}

	return nil
}

// ensureClone ensures a blobless clone of the module's origin repo exists in the cache.
func ensureClone(cfg gitInfoConfig, origin modules.ModuleOrigin) (string, error) {
	key := "repo_" + hashing.XxHashFromStringHexEncoded(origin.URL)
	info, err := cfg.GitInfoCache.GetOrCreateInfo(key, func(id string) error {
		cloneDir := cfg.GitInfoCache.AbsFilenameFromID(id)
		if err := os.MkdirAll(cloneDir, 0o777); err != nil {
			return err
		}

View on GitHub (pinned to 52c9bd7908)