{"record":{"id":"03dcc8df151d636c","repo":"gitbutlerapp/gitbutler","slug":"cannot-recreate-a-workspace-without-an-existing-workspace","errorCode":null,"errorMessage":"Cannot recreate a workspace without an existing workspace reference","messagePattern":"Cannot recreate a workspace without an existing workspace reference","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but-api/src/workspace.rs","lineNumber":66,"sourceCode":"    let mut guard = ctx.exclusive_worktree_access();\n    workspace_recreate_with_perm(ctx, guard.write_permission())\n}\n\n/// Recreate the workspace under caller-held exclusive access, recording one undo snapshot.\n///\n/// See [`workspace_recreate()`] for behavior and preconditions. No snapshot is prepared\n/// when already on the workspace.\npub fn workspace_recreate_with_perm(\n    ctx: &mut but_ctx::Context,\n    perm: &mut RepoExclusive,\n) -> anyhow::Result<WorkspaceRecreateResult> {\n    let already_on_workspace = {\n        let (repo, ws, _db) = ctx.workspace_and_db_with_perm(perm.read_permission())?;\n        match &ws.kind {\n            but_graph::workspace::WorkspaceKind::Managed { .. }\n            | but_graph::workspace::WorkspaceKind::ManagedMissingWorkspaceCommit { .. } => true,\n            but_graph::workspace::WorkspaceKind::AdHoc => {\n                anyhow::ensure!(\n                    repo.try_find_reference(but_core::WORKSPACE_REF_NAME)?\n                        .is_some(),\n                    \"Cannot recreate a workspace without an existing workspace reference\"\n                );\n                false\n            }\n        }\n    };\n\n    let maybe_oplog_entry = if already_on_workspace {\n        None\n    } else {\n        but_oplog::UnmaterializedOplogSnapshot::from_details_with_perm(\n            ctx,\n            SnapshotDetails::new(OperationKind::SwitchToWorkspace),\n            perm.read_permission(),\n            DryRun::No,\n        )","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/58e5313667b857ef39a730e380af31816a7b1768/crates/but-api/src/workspace.rs#L48-L84","documentation":"`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.","triggerScenarios":"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.","commonSituations":"Manually deleting the workspace ref; a crashed/interrupted workspace initialization; cloning a repo without GitButler's refs and attempting workspace recreation.","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"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// check the workspace ref exists before recreating\nlet has_ws_ref = repo.try_find_reference(but_core::WORKSPACE_REF_NAME)?.is_some();\nif !has_ws_ref {\n    // fall back to workspace init/apply instead of recreate\n}","typeGuard":null,"tryCatchPattern":"match workspace_recreate(ctx) {\n    Err(e) if e.to_string().contains(\"without an existing workspace reference\") => workspace_init(ctx),\n    other => other,\n}","preventionTips":["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"],"tags":["git","workspace","missing-ref"],"backgroundTag":"resource-not-found","analyzedSha":"58e5313667b857ef39a730e380af31816a7b1768","analyzedAt":"2026-09-18T06:50:32.052Z","contentChangedAt":"2026-09-18T06:50:32.052Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}