gohugoio/hugo · error

failed to clone %s: %v

Error message

failed to clone %s: %v

What it means

When `enableGitInfo` is on and the site uses Hugo Modules backed by Git, Hugo (since v0.157.0) lazily creates a blobless clone of each module's origin repository in its GitInfo cache so it can attach commit metadata to module-mounted content. This error means ensureClone failed to produce that cached clone for the module's origin URL.

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 8a468df065)

Solutions

1. Check the wrapped error: if it's an exec/security error, allow git via `[security.exec] allow = ['^git$', ...]`; if network/auth, provide credentials (e.g. git credential helper or GIT_CONFIG token rewrite) for the module origin.
2. Ensure the git binary is installed in the build environment.
3. Verify the origin URL is reachable from the build machine (`git ls-remote <url>`).
4. If module GitInfo isn't needed, disable enableGitInfo or avoid it in offline CI.
5. Clear a corrupted GitInfo cache (hugo's cacheDir gitinfo entries) and rebuild.

// verify git is available and remote reachable before enabling GitInfo
if _, err := exec.LookPath("git"); err != nil { log.Fatal("git not on PATH") }
exec.Command("git", "ls-remote", "--exit-code", repoURL, "HEAD").Run()

for attempt := 0; attempt < 3; attempt++ {
    err = build()
    if err == nil || !strings.Contains(err.Error(), "failed to clone") { break }
    time.Sleep(time.Duration(1<<attempt) * time.Second) // transient network
}

When it happens

Trigger: A build with enableGitInfo=true and Git-backed modules where `git clone --filter=blob:none --no-checkout <origin.URL> <cacheDir>` cannot run or complete: git binary missing or blocked by Hugo's security exec allowlist, no network access to the origin URL, auth required for a private module repo, or the cache directory not writable (os.MkdirAll failure).

Common situations: CI environments without network egress or git credentials for private module repos; sandboxed builds (Netlify/Vercel/Docker) missing the git binary; upgrading to Hugo ≥0.157.0 which added module GitInfo and suddenly attempting clones that older versions never did; `security.exec.allow` not permitting `git`.

Related errors

• failed to map git repo for module %s: %v
• failed to load Git data: %w
• failed to load modules: %w
• failed to create config from modules config: %w
• no modules loaded (need at least the main module)

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