What causes "failed to lookup %s branch for repo %s: %w" in GoogleContainerTools/skaffold?

Run `git ls-remote --heads ` manually to see the underlying git error.

failed to lookup %s branch for repo %s: %w

Error message

failed to lookup %s branch for repo %s: %w

What it means

branchExists runs `git ls-remote --heads <repoCloneURI> <branch>` to check whether a branch exists on the remote. If that command fails (non-zero exit), the error — OS errors, git authentication/permission errors, or a nonexistent/unreachable repo — is wrapped with this message. It is a hard failure distinct from 'branch simply absent' (empty output returns false, nil).

Source

Thrown at pkg/skaffold/git/gitutil.go:77

	if masterExists {
		return masterRef, nil
	} else if mainExists {
		return mainRef, nil
	}
	return "", fmt.Errorf("failed to get default branch for repo %s", repo)
}

// BranchExists checks if branch is present in the input repo
func branchExists(ctx context.Context, repoCloneURI, repo, branch string) (bool, error) {
	gitProgram, err := findGit()
	if err != nil {
		return false, err
	}
	out, err := util.RunCmdOut(ctx, exec.Command(gitProgram, "ls-remote", "--heads", repoCloneURI, branch))
	if err != nil {
		// stdErr contains the error message for os related errors, git permission errors
		// and if repo doesn't exist
		return false, fmt.Errorf("failed to lookup %s branch for repo %s: %w", branch, repo, err)
	}
	// stdOut contains the branch information if the branch is present in remote repo
	// stdOut is empty if the repo doesn't have the input branch
	if strings.TrimSpace(string(out)) != "" {
		return true, nil
	}
	return false, nil
}

// getRepoDir returns the cache directory name for a remote repo
func getRepoDir(g Config) (string, error) {
	inputs := []string{g.Repo, g.Ref}
	hasher := sha256.New()
	enc := json.NewEncoder(hasher)
	if err := enc.Encode(inputs); err != nil {
		return "", err
	}

View on GitHub (pinned to a1189de023)

Solutions

Run `git ls-remote --heads <repoCloneURI> <branch>` manually to see the underlying git error.
Fix authentication: add SSH keys (ssh -T git@github.com), configure a credential helper/PAT, or switch the clone URI between https and ssh as appropriate.
Verify the repo URI is correct and the repository exists and is accessible to your account.
Ensure the git binary is installed and on PATH (git --version); check network/proxy/VPN access to the git host.

Example fix

# before
$ skaffold run   # fails: failed to lookup main branch ... Permission denied (publickey)
# after
$ ssh-keygen -t ed25519 && ssh -T git@github.com   # register key with host
git:
  repo: git@github.com:org/repo   # ssh URI matching configured key

Defensive patterns

Strategy: try-catch

Validate before calling

git ls-remote --heads "$REPO_CLONE_URI" "$BRANCH" >/dev/null 2>&1 \
  || echo "Cannot reach repo or authenticate: check URI, SSH keys, and credentials"
git --version >/dev/null 2>&1 || echo "git not installed or not on PATH"

Type guard

func isGitAuthError(err error) bool {
    msg := err.Error()
    return strings.Contains(msg, "Permission denied") ||
        strings.Contains(msg, "Authentication failed") ||
        strings.Contains(msg, "could not read Username")
}

Try / catch

path, err := git.SyncRepo(ctx, cfg, opts)
if err != nil {
    if strings.Contains(err.Error(), "failed to lookup") && strings.Contains(err.Error(), "branch") {
        log.Warnf("git ls-remote failed for %s; check `git ls-remote --heads %s` output: %v",
            cfg.Repo, cfg.RepoCloneURI, err)
        return err
    }
    return err
}

Prevention

Ensure git is installed and on PATH in every environment (CI images, devcontainers).
Configure deploy keys / SSH agent forwarding or credential helpers before running skaffold.
Validate the repoCloneURI format (https vs ssh) matches your configured credentials.
Run `git ls-remote` as a smoke test in CI pipelines before build steps.
In containers, pre-accept git host keys (ssh-keyscan) to avoid interactive verification failures.

When it happens

Trigger: Called from defaultRef during syncRepo when `git ls-remote --heads` exits non-zero: git binary issues, remote URI unreachable, bad credentials/SSH key, or repository does not exist or access denied.

Common situations: Private repo without SSH keys or credential helper configured; repo URL typo or repo deleted; SSH host key verification failing in CI containers; git not on PATH; firewall blocking github.com/company git server; expired PAT.

Related errors

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/85de1d4ab5a86d76. Report an issue: GitHub.