What causes "Cannot create reference on unborn branch '{}'" in gitbutlerapp/gitbutler?

Create the initial commit on the branch first (e.g. `git commit --allow-empty -m init`) so the branch is born.

Cannot create reference on unborn branch

Error message

Cannot create reference on unborn branch '{}'

What it means

During `apply`, if the workspace's reference (`ws.ref_name()`) does not exist in the repository, the workspace is assumed to be an ad-hoc/unborn workspace whose HEAD branch has never been created. Creating a reference on such an unborn branch is not supported, so the operation bails with the shortened ref name.

Solutions

Create the initial commit on the branch first (e.g. `git commit --allow-empty -m init`) so the branch is born.
Point the workspace at an existing branch with commits instead of the unborn one.
Verify with `git rev-parse --verify <branch>` before invoking apply that the ref exists.

Example fix

// before (empty repo)
ws.branch_apply(repo, &branch, ...).await?;
// after
git.commit("HEAD", "init", tree, ...)?; // or ensure repo has an initial commit first
ws.branch_apply(repo, &branch, ...).await?;

Defensive patterns

Strategy: validation

Validate before calling

if let Some(ws_ref) = ws.ref_name() {
    if repo.try_find_reference(ws_ref)?.is_none() {
        return Err("workspace branch is unborn; create an initial commit first");
    }
}

Try / catch

// Rust
if let Err(e) = ws.branch_apply(repo, branch, ...).await {
    if e.to_string().starts_with("Cannot create reference on unborn branch") {
        eprintln!("initialize the repository with a first commit before applying");
        return Err(e);
    }
    return Err(e);
}

Prevention

Require at least one commit before running GitButler apply operations.
Detect empty repos up front with `git rev-parse --verify HEAD`.
Guard against workflows that delete the workspace branch ref.

When it happens

Trigger: Calling `apply` against a workspace whose ref (e.g. `refs/heads/main` in a fresh repo with no commits yet) cannot be found via `repo.try_find_reference`.

Common situations: Running GitButler operations in a freshly `git init`ed repository with zero commits; a corrupted/deleted HEAD branch; pointing the tool at an empty worktree.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/d2803ed8423629a1. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-workspace/src/branch/apply.rs:351

            ws_ref_name.as_ref().map(|rn| rn.as_ref()),
        )?;

        // When exiting early, don't try to adjust the ws commit.
        return Ok(Outcome {
            workspace: ws,
            status: OutcomeStatus::Applied,
            workspace_ref_created: false,
            workspace_merge: None,
            conflicting_stacks: Vec::new(),
            applied_branches,
        });
    };

    if let Some(ws_ref_name) = ws.ref_name()
        && repo.try_find_reference(ws_ref_name)?.is_none()
    {
        // The workspace is the probably ad-hoc, and doesn't exist, *assume* unborn.
        bail!(
            "Cannot create reference on unborn branch '{}'",
            ws_ref_name.shorten()
        );
    }

    if ws.has_workspace_commit_in_ancestry(repo) {
        bail!("Refusing to work on workspace whose workspace commit isn't at the top");
    }

    if meta.workspace_opt(branch.as_ref())?.is_some() {
        bail!(
            "Refusing to apply a reference that already is a workspace: '{}'",
            branch.shorten()
        );
    }
    // In general, we only have to deal with one branch to apply. But when we are on an adhoc workspace,
    // we need to assure both branches go into the existing or the new workspace:
    //  - the current one and the one to apply, if these are different.

View on GitHub (pinned to 58e5313667)