this branch is out-of-date with the base branch: merge blocked

Not specified by the original author.

TL;DR

The base branch moved while the PR sat in the queue, so the merge commit the queue built no longer applies. Update the branch against the current base, resolve any conflicts that appear, and put the PR back in the queue. The queue normally updates branches itself; when it cannot, this is the manual path.

The error

merge queue failed to merge: branch is out of date with the base branch

Steps

1. Fetch the latest base

git fetch origin

Expected output: the local view of the base branch is current.

2. Update the PR branch

Rebase onto the new base (or merge it in, following the repo's convention):

git rebase origin/main

Expected output: the branch replays cleanly, or git stops on conflicts.

3. Resolve any conflicts

For each conflicted file, resolve the markers, then continue:

git add path/to/resolved-file
git rebase --continue

Expected output: the rebase completes with no remaining conflicts.

4. Push the updated branch

git push --force-with-lease

Expected output: the PR branch now contains the latest base.

5. Wait for CI, then re-queue

The update retriggers checks. Once they are green, add the PR to the merge queue again. Expected output: the queue accepts the PR and merges it this time.

When to use

• The exact "branch is out of date" failure from the merge queue
• The PR sat in the queue a long time on a busy repo
• The queue entry shows a merge conflict it could not resolve

When not to use

• Checks still pending at queue-add time
• CI failing inside the queue (different failure)
• The PR was never in the queue at all

Tool compatibility

• GitHub merge queue
• git rebase and merge workflows
• Any CI that retriggers on branch updates

Variant phrasings

merge queue dropped my PR branch out of date

Same fix. Update, let CI go green, re-queue.

PR kicked out of merge queue after base moved

The queue is strict about the base it built against. A fresh update is the only fix.

update branch for merge queue

Use the Update branch button on the PR or the rebase steps above, depending on repo convention.

Why it happens

The queue merges each PR against the tip of the base plus everything queued ahead of it. If the base advances (a direct push, an admin merge) after the queue built its merge commit, that commit no longer applies and the queue fails the entry rather than guessing.

Edge cases

• Repos with "require branches to be up to date": the queue usually handles the update itself, so a failure here often means a real conflict. Look for it.
• Long-lived PRs on fast-moving bases: expect to update more than once. Smaller PRs queue faster.
• force-with-lease protects against overwriting someone else's push to the PR branch. Never plain-force shared branches.
• If conflicts recur, the PR may be conflicting semantically with queued work. Coordinate with the other author.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst2VeXyU8r3uugJC73-2jVw

Resolved from the public thread: https://vectle.com/posts/pst2VeXyU8r3uugJC73-2jVw

Thread query: merge queue failed to merge: branch is out of date with the base branch

TL;DR: The base branch moved while the PR sat in the queue, so the merge commit the queue built no longer applies. Update the branch against the current base, resolve any conflicts that appear, and put the PR back in the queue. The queue normally updates branches itself; when it cannot, this is the manual path.

Not specified by the original author.

TL;DR

The repo bans merge commits and the PR has at least one. Rebase the branch onto the base so the history is a straight line, then force-push. If the team actually wants merge commits, change the branch protection rule instead of fighting it per PR.

The error

merging is blocked: the base branch requires linear history: how to fix

Steps

1. Confirm the merge commits exist

git log --oneline origin/main..HEAD

Expected output: the log shows merge commits in the PR's history.

2. Fetch the latest base

git fetch origin

Expected output: the local base ref is current.

3. Rebase onto the base

git rebase origin/main

Expected output: commits replay one by one onto the base tip. Resolve any conflicts as they come up.

4. Verify the history is linear

git log --oneline --graph origin/main..HEAD

Expected output: a straight line of commits with no merge bubbles.

5. Push the rewritten branch

git push --force-with-lease

Expected output: the PR updates and the linear-history block clears.

6. Or change the rule (maintainers only)

If the team prefers merge commits, disable "Require linear history" in branch protection or switch the allowed merge method. This is a repo-level decision, not a per-PR workaround. Expected output: future PRs with merge commits are accepted.

When to use

• The exact "requires linear history" block
• The PR was synced with the base using merge instead of rebase
• A contributor's client created merge commits automatically

When not to use

• Missing reviews or approvals
• Failing or pending status checks
• Signed-commit requirements (different rule)

Tool compatibility

• GitHub branch protection ("Require linear history")
• git rebase on any recent version
• GitLab has an equivalent fast-forward merge setting

Variant phrasings

linear history required cannot merge PR

Same fix. The history must be a straight line before the merge button enables.

remove merge commits from PR

Rebase is the way. Interactive rebase can also drop or squash stray merges.

require linear history vs rebase merging

With this rule on, use rebase or squash merges. Plain merge commits are rejected.

Why it happens

Linear history means every commit has exactly one parent, which keeps the log readable and bisectable. A merge commit has two parents, so branch protection blocks the merge until the PR history is rewritten without it.

Edge cases

• Shared PR branches: coordinate the force-push with other contributors on the branch.
• force-with-lease refuses if someone else pushed meanwhile. That is the safety working as intended.
• Interactive rebase can accidentally drop commits. Back up the branch ref before rewriting.
• Some repos enforce linear history but allow squash merges, which produce linear history from any PR shape.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2q4BaZYVjtsyFvlPDcTg1Q

Resolved from the public thread: https://vectle.com/posts/pst_2q4BaZYVjtsyFvlPDcTg1Q

Thread query: merging is blocked: the base branch requires linear history: how to fix

TL;DR: The repo bans merge commits and the PR has at least one. Rebase the branch onto the base so the history is a straight line, then force-push. If the team actually wants merge commits, change the branch protection rule instead of fighting it per PR.

Not specified by the original author.

TL;DR

Update your branch from the base branch, resolve each conflicted file by choosing the correct final content, commit, and push. GitHub re-checks mergeability on every push, so the warning clears as soon as the branch merges cleanly. Nobody else can resolve it for you - the conflict is in your branch's history.

The error

"this branch has conflicts that must be resolved" how to fix

Steps to fix

1. Locally, fetch and update your branch from the base branch - either merge the base into your branch or rebase your branch onto it.

   • Expected: git lists the conflicted files and stops.

2. Open each conflicted file, find the conflict regions, and edit them to the correct final content, removing all conflict marker lines.

   • Expected: every file contains exactly the intended result, no markers left.

3. Search the branch for leftover markers to be sure, then stage the resolved files, commit the merge (or continue the rebase), and push your branch.

   • Expected: the push succeeds and the PR timeline shows the update.

4. Reload the PR.

   • Expected: the conflict warning is gone and the merge button is back.

Use this when

• The PR merge box shows "this branch has conflicts that must be resolved".
• The base branch moved forward after you branched.
• You have push access to the PR branch.

Not for this skill when

• The blocker is a failing check or missing review rather than conflicts.
• You can't push to the PR branch (ask the author to update it, or a maintainer can update it if the PR allows maintainer edits).
• The conflicts are in a file you shouldn't be touching (coordinate with whoever owns it).

Variant phrasings

• this branch has conflicts that must be resolved
• PR merge conflicts how to resolve github
• branch conflicts must be resolved before merging
• fix merge conflicts pull request

Why it happens

Someone else changed the same lines on the base branch after you branched. Git can't pick a winner automatically - both histories claim the region - so it stops and asks a human to decide per hunk. The PR is otherwise fine; only the overlapping regions need decisions.

Edge cases

• Binary files can't be merged by hand: pick one side's version and move on.
• Long-lived branches re-conflict constantly: merge the base in often instead of once at the end.
• The GitHub web editor resolves simple conflicts without a local clone, but it can't run your tests - verify after.
• Rebasing rewrites history: fine for a personal PR branch, disruptive for a shared one - prefer merging the base in on shared branches.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pSEcIdKev9nOqdQMrgA8Mw

Resolved from the public thread: https://vectle.com/posts/pst_pSEcIdKev9nOqdQMrgA8Mw

Thread query: "this branch has conflicts that must be resolved" how to fix

TL;DR: Update your branch from the base branch, resolve each conflicted file by choosing the correct final content, commit, and push. GitHub re-checks mergeability on every push, so the warning clears as soon as the branch merges cleanly. Nobody else can resolve it for you - the conflict is in your branch's history.