gohugoio/hugo · error

failed to clone

Error message

failed to clone %s: %v

What it means

Emitted during git-info module loading when ensureClone() fails to create/refresh the blobless clone of a module's origin repository in the gitinfo cache. The %s is the origin URL; %v is the underlying failure.

Solutions

1. Run `git clone <origin-url>` manually with the same credentials to confirm reachability.
2. Ensure git is installed and on PATH in the build environment (`git --version`).
3. Verify the gitinfo cache dir (under HUGO_CACHEDIR) is writable; chmod or pick a writable dir.
4. If the module is private, configure git credentials/SSH key or a deploy token before building.
5. Temporarily disable gitinfo (no .gitinfo / set enableGitInfo=false) to confirm it is the culprit.

Example fix

# before: private module, no credentials
git clone https://github.com/myorg/privaterepo.git  # fails

# after: provide credentials via env or git config
git config --global url."git@github.com:".insteadOf "https://github.com/
export HUGO_CACHEDIR=/tmp/hugocache

// Before enabling gitinfo, verify git availability and reachability of each module origin.
if _, err := exec.LookPath("git"); err != nil { return errors.New("git not found") }
for _, o := range origins { if err := pingOrigin(o.URL); err != nil { return err } }

if err := g.loadModuleRepos(cfg); err != nil {
    // gitinfo is optional; log and continue without git data rather than fail the build
    cfg.Logger.Warnf("gitinfo modules skipped: %v", err)
}

When it happens

Trigger: Raised in loadModuleRepos at gitinfo.go:171 when ensureClone(cfg, origin) returns an error for a module that isGitModule(mod). Occurs when the git clone command cannot be constructed or run, or the cache dir cannot be created.

Common situations: No network access or git credentials for a private module origin URL; git not installed or not on PATH inside the build container; gitinfo cache directory not writable (HUGO_CACHEDIR on read-only FS); origin URL mistyped in the module definition.

Related errors

• git clone
• failed to map git repo for module
• git clone
• cache dir contains unresolved placeholders
• could not determine content directory for

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

Appendix: source

Thrown at hugolib/gitinfo.go:171

	g.contentDir = gitRepo.TopLevelAbsPath
	g.repo = gitRepo

	return g, nil
}

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)

View on GitHub (pinned to 52c9bd7908)