{"record":{"id":"a2204b3c13b9da02","repo":"gitbutlerapp/gitbutler","slug":"but-merge-requires-an-active-gitbutler-workspace-gitbutler","errorCode":null,"errorMessage":"`but merge` requires an active GitButler workspace (`gitbutler/workspace`). Switch into the workspace and try again.","messagePattern":"`but merge` requires an active GitButler workspace \\(`gitbutler/workspace`\\)\\. Switch into the workspace and try again\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but-api/src/land/mod.rs","lineNumber":185,"sourceCode":"///\n/// This fetches the target, lands the branch (fast-forward or signed merge commit, retrying when\n/// the target moves underneath us), then reconciles the remaining applied branches onto the moved\n/// target. The remote push is not undoable; see [`BranchLandResult::reconcile_skipped`] and the\n/// workspace state for what to report.\n#[but_api(napi, try_from = json::BranchLandResult)]\n#[instrument(skip(ctx), err(Debug))]\npub fn branch_land(\n    ctx: &mut Context,\n    branch: String,\n    no_ff: bool,\n    whole_stack: bool,\n) -> anyhow::Result<BranchLandResult> {\n    let base_branch = {\n        let mut guard = ctx.exclusive_worktree_access();\n        {\n            let (_repo, ws, _db) = ctx.workspace_and_db_with_perm(guard.read_permission())?;\n            if !ws.kind.has_managed_ref() {\n                bail!(\n                    \"`but merge` requires an active GitButler workspace (`gitbutler/workspace`). \\\n                     Switch into the workspace and try again.\"\n                );\n            }\n        }\n        crate::legacy::virtual_branches::get_base_branch_data(ctx, guard.write_permission())?\n            .ok_or_else(|| anyhow::anyhow!(\"No base branch configured\"))?\n    };\n\n    let target_branch_name = base_branch.short_name.clone();\n    if target_branch_name.is_empty() {\n        bail!(\"Configured target branch has no branch name\");\n    }\n    let fetch_remote_name = base_branch.remote_name.clone();\n    let push_remote_name = if base_branch.push_remote_name.is_empty() {\n        fetch_remote_name.clone()\n    } else {\n        base_branch.push_remote_name.clone()","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/58e5313667b857ef39a730e380af31816a7b1768/crates/but-api/src/land/mod.rs#L167-L203","documentation":"`but merge` operates on a GitButler-managed workspace, which is identified by the `gitbutler/workspace` ref. `branch_land` checks that the loaded workspace has a managed ref and bails if the repository is not currently in an active (initialized) GitButler workspace.","triggerScenarios":"Calling `but merge <branch>` in a repo where the workspace is not active — `ws.kind.has_managed_ref()` is false because `gitbutler/workspace` is absent or the workspace kind has no managed ref (e.g. plain git checkout, workspace switched off).","commonSituations":"Running the command in a plain Git repo never initialized with GitButler; after `but switch`-style operations that left the workspace; working in a bare or unrelated checkout.","solutions":["Initialize/enter the GitButler workspace for the repository (e.g. `but init` / open the repo in the GitButler app) and retry","Switch into the workspace so `gitbutler/workspace` exists, then re-run `but merge`","If GitButler was uninstalled or the ref was deleted, re-create the workspace or fall back to a plain `git merge` into the target branch"],"exampleFix":"# before\nbut merge feature-branch\n# error: requires an active GitButler workspace\n\n# after\nbut init   # or open in GitButler to create gitbutler/workspace\nbut merge feature-branch","handlingStrategy":"validation","validationCode":"if !repo.path().join(\"gitbutler/workspace\").exists()\n    && repo.find_reference(\"refs/gitbutler/workspace\").is_err() {\n    println!(\"not in an active GitButler workspace; run `but init`\");\n    return Ok(());\n}","typeGuard":null,"tryCatchPattern":"match land_result {\n    Err(e) if e.to_string().contains(\"requires an active GitButler workspace\") => {\n        initialize_workspace();\n        retry_land();\n    }\n    other => other?,\n}","preventionTips":["Run `but init` (or open the repo in the GitButler app) before using `but` commands","Check `but status` to confirm an active workspace before scripting merges","Don't delete the `gitbutler/workspace` ref manually"],"tags":["gitbutler","workspace","precondition","landing"],"backgroundTag":"invalid-state-transition","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"}