BloopAI/vibe-kanban · warning

Force push required. The remote branch has diverged.

Error message

Force push required. The remote branch has diverged.

What it means

The push action calls workspacesApi.push(); when the backend detects the local branch and its remote counterpart have diverged, it returns an error envelope typed force_push_required. The action translates that typed error into this explicit message telling the user a force push (history rewrite) is needed rather than a normal push.

Source

Thrown at packages/web-core/src/shared/actions/index.ts:1086

    },
  },

  GitPush: {
    id: 'git-push',
    label: 'Push',
    icon: ArrowUpIcon,
    shortcut: 'X U',
    requiresTarget: ActionTargetType.GIT,
    isVisible: (ctx) =>
      ctx.hasWorkspace &&
      ctx.hasGitRepos &&
      ctx.hasOpenPR &&
      ctx.hasUnpushedCommits,
    execute: async (ctx, workspaceId, repoId) => {
      const result = await workspacesApi.push(workspaceId, { repo_id: repoId });
      if (!result.success) {
        if (result.error?.type === 'force_push_required') {
          throw new Error(
            'Force push required. The remote branch has diverged.'
          );
        }
        throw new Error('Failed to push changes');
      }
      invalidateWorkspaceQueries(ctx.queryClient, workspaceId);
    },
  },

  // === Repo-specific Actions (for command bar when selecting a repo) ===
  RepoCopyPath: {
    id: 'repo-copy-path',
    label: 'Copy Repo Path',
    icon: CopyIcon,
    requiresTarget: ActionTargetType.GIT,
    isVisible: (ctx) => ctx.hasWorkspace && ctx.hasGitRepos,
    execute: async (_ctx, _workspaceId, repoId) => {
      try {

View on GitHub (pinned to 4deb7eca8f)

Solutions

1. Pull/rebase local work onto the remote branch, then push normally (preferred — preserves remote history).
2. If divergence is intentional, confirm and perform an explicit force push (ideally --force-with-lease).
3. Coordinate with collaborators before force pushing a shared branch.
4. Investigate what rewrote remote history to prevent recurrence.

Example fix

// before
const result = await workspacesApi.push(workspaceId, { repo_id: repoId }); // fails: diverged
// after
if (!result.success && result.error?.type === 'force_push_required') {
  await git.fetch();
  await git.rebaseOnto('origin/' + branch); // or confirmForcePush flow
  await workspacesApi.push(workspaceId, { repo_id: repoId, force: true });
}

// before pushing: detect divergence client-side
await git.fetch();
const diverged = await git.isBranchDiverged(branch, 'origin/' + branch);
if (diverged) await promptRebaseOrForcePush();

function isForcePushRequired(e: unknown): e is { type: 'force_push_required' } {
  return typeof e === 'object' && e !== null && (e as { type?: string }).type === 'force_push_required';
}

try {
  await pushAction.execute(ctx, workspaceId, repoId);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Force push required')) {
    const ok = await confirmDialog('Remote branch diverged. Rebase or force push?');
    if (ok) await pushWithForce(workspaceId, repoId);
  } else throw e;
}

When it happens

Trigger: execute() -> workspacesApi.push(workspaceId, { repo_id }) resolves with { success: false, error: { type: 'force_push_required' } } — remote commits were rewritten (amend/rebase) or another machine force-pushed, so a fast-forward push is impossible.

Common situations: Rebased or amended commits that were already pushed; collaborator force-pushed the shared branch; remote branch reset from another workspace; CI/bot rewriting history.

Related errors

• Failed to push changes
• result.message || 'Force push failed'
• result.message || 'Push failed'
• branch_fetch_failed
• pr_not_found

AI-assisted analysis of BloopAI/vibe-kanban@4deb7eca8f (2026-08-29). Data as JSON: /api/errors/0fa29c37f5b6957c. Report an issue: GitHub.