# Troubleshoot Rebase

> Diagnose and recover from git rebase failures Use when this capability is needed.

- Skill: `tomevault-io/troubleshoot-rebase` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/troubleshoot-rebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/troubleshoot-rebase/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/troubleshoot-rebase

---


# Git Rebase Troubleshoot

Diagnose and recover from rebase failures. Invoke when standard rebase error handling cannot resolve the issue.

## Quick Diagnosis

Check: `pwd`, `git status`, `git branch --show-current`, `git worktree list`, `gh pr view`.

## Error: Push Rejected (Non-Fast-Forward)

Branches have diverged. First, confirm your current branch: `git branch --show-current`.

- If this is a **feature branch** (for example `feature/foo`) and the push was rejected:
  - Rebase onto the latest main: `git fetch origin --force && git rebase origin/main`
  - Then push your feature branch: `git push --force-with-lease origin HEAD`

- If you are on **main** and are behind `origin/main`, do **not** rebase main:
  - Update main: `git fetch origin --force && git reset --hard origin/main`
  - Then retry your original operation (for example, rebase your feature branch onto main and push the feature branch).

If the rebase fails because `origin/main` moved again, repeat: fetch, rebase your feature branch, then push with `--force-with-lease`.

## Error: Repository Rule Violations

GH013 error about PR/status checks. This is NOT a block if commits are from approved PR.

**Causes**: CI not passing, reviews not approved, merge conflict.

**Fix order**: Rebase feature -> push (triggers CI) -> wait for checks -> merge to main -> push.

Check: `gh pr view <branch> --json checks,reviews,statusCheckRollup`

## Error: Embedded Git Repository

Nested .git directory found. Fix: `git rm --cached <folder-name>` or add to `.gitignore`.

## Rebase Conflict

Identify: `git status`, `git diff --name-only --diff-filter=U`

Resolve: edit files, `git add <file>`, then `git rebase --continue` (or `--abort`).

## Error: Fast-Forward Merge Failed

Main was updated between rebase and merge. Run `git fetch origin --force && git reset --hard origin/main`, then retry.

## Error: Feature Branch Push Failed

Fix: `git push --force-with-lease origin <branch>`

## Recovery: Aborting In-Progress Rebase

`git rebase --abort && git status`

## Verification

Before retrying:

- Main synced: `git diff origin/main --stat` (should be empty)
- Branch clean: `git status`
- No rebase in progress: check `.git/rebase-{merge,apply}` doesn't exist
- PR state: `gh pr view <branch> --json state`

## Escalation

If unresolved: check `git reflog`, review `git log -10 --oneline`, ask user.

**DO NOT**: Use `--force` (use `--force-with-lease`), use `gh pr merge`, run `git rebase -i`.

## Related Skills

- **rebase-pr** (git-workflows) — Standard rebase-merge PR workflow this skill troubleshoots
- **troubleshoot-precommit** (git-workflows) — Troubleshoot pre-commit hook failures during rebase
- **troubleshoot-worktree** (git-workflows) — Troubleshoot git worktree, branch, and refname issues

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jacobpevans) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->