argoproj/argo-workflows · error

single branch mode without a branch specified

Error message

single branch mode without a branch specified

What it means

The git artifact driver refuses to clone when `singleBranch: true` is set on the artifact but no `branch` is specified. Single-branch mode tells go-git to fetch only one branch's history, so a branch name is mandatory to know which ref to clone. This is an upfront configuration validation, thrown before any network I/O.

Source

Thrown at workflow/artifacts/git/git.go:126

		transport.UnsupportedCapabilities = newCaps
	}

	sshUser := GetUser(a.Repo)
	closer, auth, err := g.auth(sshUser)
	if err != nil {
		return err
	}
	defer closer()
	depth := a.GetDepth()
	cloneOptions := &git.CloneOptions{
		URL:             a.Repo,
		Auth:            auth,
		Depth:           depth,
		SingleBranch:    a.SingleBranch,
		InsecureSkipTLS: g.InsecureSkipTLS,
	}
	if a.SingleBranch && a.Branch == "" {
		return errors.New("single branch mode without a branch specified")
	}
	if a.SingleBranch {
		cloneOptions.ReferenceName = plumbing.NewBranchReferenceName(a.Branch)
	}

	r, err := git.PlainClone(path, false, cloneOptions)
	if errors.Is(err, transport.ErrEmptyRemoteRepository) {
		logging.RequireLoggerFromContext(ctx).Info(ctx, "Cloned an empty repository")
		var initErr error
		r, initErr = git.PlainInit(path, false)
		if initErr != nil {
			return fmt.Errorf("failed to plain init: %w", initErr)
		}
		if _, remoteErr := r.CreateRemote(&config.RemoteConfig{Name: git.DefaultRemoteName, URLs: []string{a.Repo}}); remoteErr != nil {
			return fmt.Errorf("failed to create remote %q: %w", a.Repo, remoteErr)
		}
		branchName := a.Revision
		if branchName == "" {

View on GitHub (pinned to 35bff19146)

Solutions

1. Set the `branch` field on the git artifact, e.g. `branch: main`, whenever `singleBranch: true`.
2. If the branch comes from a template parameter, give the parameter a default or validate it is non-empty before submit.
3. If you don't need single-branch behavior, remove `singleBranch: true` so the default branch is cloned.

Example fix

# before
artifacts:
- git:
    repo: https://github.com/org/repo.git
    singleBranch: true
# after
artifacts:
- git:
    repo: https://github.com/org/repo.git
    singleBranch: true
    branch: main

wf, _ := wfv1.NewWorkflow(...)
for _, a := range wf.Spec.Templates {
    if a.Git != nil && a.Git.SingleBranch && a.Git.Branch == "" {
        return fmt.Errorf("git artifact in template %q sets singleBranch without branch", a.Name)
    }
}

When it happens

Trigger: Calling Load() on a git artifact whose spec sets `singleBranch: true` while `branch` is empty/omitted.

Common situations: Users set singleBranch to speed up clones of large repos but forget to name the branch; templates that parameterize branch (e.g. `branch: '{{workflow.parameters.branch}}'`) where the parameter resolves to an empty string.

Related errors

• failed to evaluate stop expression: %w
• no valid source is used for data template
• invalid TTL
• memoization configmap doesn't have %s label, refusing to use
• duplicate synchronization item found

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/3cb25accecfc9598. Report an issue: GitHub.