Cannot recreate a workspace without an existing workspace…

Error message

Cannot recreate a workspace without an existing workspace reference

What it means

`workspace_recreate_with_perm` refuses to recreate a workspace when the repository is in AdHoc workspace mode but the `but_core::WORKSPACE_REF_NAME` reference does not exist in the repo. Recreation needs that reference as the basis; without it there is nothing to recreate from.

Solutions

Create or restore the workspace reference before recreating (or use workspace init/apply instead of recreate)
Re-apply the project in the GitButler UI so the workspace ref is recreated
Check `git rev-parse --verify <workspace-ref>` to confirm the ref exists first

Defensive patterns

Strategy: validation

Validate before calling

// check the workspace ref exists before recreating
let has_ws_ref = repo.try_find_reference(but_core::WORKSPACE_REF_NAME)?.is_some();
if !has_ws_ref {
    // fall back to workspace init/apply instead of recreate
}

Try / catch

match workspace_recreate(ctx) {
    Err(e) if e.to_string().contains("without an existing workspace reference") => workspace_init(ctx),
    other => other,
}

Prevention

Never manually delete the GitButler workspace ref
Use the app's own project removal instead of manual git ref deletion
Verify ref existence before invoking recreate

When it happens

Trigger: Calling `workspace_recreate` on a repo whose workspace kind is `AdHoc` and where the workspace reference (e.g. refs/heads/gitbutler/workspace) is missing — e.g. it was deleted or never created.

Common situations: Manually deleting the workspace ref; a crashed/interrupted workspace initialization; cloning a repo without GitButler's refs and attempting workspace recreation.

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/03dcc8df151d636c. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-api/src/workspace.rs:66

    let mut guard = ctx.exclusive_worktree_access();
    workspace_recreate_with_perm(ctx, guard.write_permission())
}

/// Recreate the workspace under caller-held exclusive access, recording one undo snapshot.
///
/// See [`workspace_recreate()`] for behavior and preconditions. No snapshot is prepared
/// when already on the workspace.
pub fn workspace_recreate_with_perm(
    ctx: &mut but_ctx::Context,
    perm: &mut RepoExclusive,
) -> anyhow::Result<WorkspaceRecreateResult> {
    let already_on_workspace = {
        let (repo, ws, _db) = ctx.workspace_and_db_with_perm(perm.read_permission())?;
        match &ws.kind {
            but_graph::workspace::WorkspaceKind::Managed { .. }
            | but_graph::workspace::WorkspaceKind::ManagedMissingWorkspaceCommit { .. } => true,
            but_graph::workspace::WorkspaceKind::AdHoc => {
                anyhow::ensure!(
                    repo.try_find_reference(but_core::WORKSPACE_REF_NAME)?
                        .is_some(),
                    "Cannot recreate a workspace without an existing workspace reference"
                );
                false
            }
        }
    };

    let maybe_oplog_entry = if already_on_workspace {
        None
    } else {
        but_oplog::UnmaterializedOplogSnapshot::from_details_with_perm(
            ctx,
            SnapshotDetails::new(OperationKind::SwitchToWorkspace),
            perm.read_permission(),
            DryRun::No,
        )

View on GitHub (pinned to 58e5313667)