How to fix error: split index base is outdated in Git

GitINTERMEDIATELOWUpdated Dec 6, 2025· 99 views

This error occurs when Git's split index optimization becomes out of sync. The split index feature stores the index in two parts to speed up operations in large repositories. The fix involves disabling and optionally re-enabling the split index mode.

Quick fix

Fixes error: split index base is outdated

# Try a simple Git command to reproduce the error
git status

# Check your current Git configuration for split index
git config --get core.splitIndex

# List files in .git directory to see index files
ls -la .git/index*
ls -la .git/sharedindex.*
  1. Verify the error and check repository status
  2. Disable split index mode
  3. Force refresh the index
  4. Disable split index in configuration
git — error
# Try a simple Git command to reproduce the error
git status
# Check your current Git configuration for split index
git config --get core.splitIndex
# List files in .git directory to see index files
ls -la .git/index*
ls -la .git/sharedindex.*
error: split index base is outdated

What this error means

The "split index base is outdated" error indicates that Git's split index feature has encountered a synchronization problem between its two component files. The split index mode is an optimization that divides the Git index (staging area) into a base shared index file and a smaller split index file containing recent changes. When you enable split index mode via `core.splitIndex` or `git update-index --split-index`, Git creates two files: - A shared index file at `$GIT_DIR/sharedindex.<SHA-1>` containing the bulk of entries - A split index file at `$GIT_DIR/index` containing only recent modifications This error appears when the split index file references a base (shared index) that no longer matches what's on disk. This can happen due to: - Repository corruption or incomplete Git operations - External tools modifying the index files directly - Race conditions with concurrent Git operations - File system issues or unexpected interruptions - Compatibility issues with third-party Git tools that don't fully support split index The split index feature is generally transparent to users, but when it breaks, you'll need to manually reset or disable it.

Typical symptoms

  • Git commands fail with 'error: split index base is outdated'
  • Repository operations suddenly stop working after a crash or interrupted operation
  • Git status, add, commit, or checkout commands all produce the same error
  • Third-party Git tools (GitPython, libgit2-based tools) fail to read the repository
  • IDE Git integrations show errors or fail to display file status
  • The error appears after enabling core.splitIndex configuration

Common causes

  1. The shared index file was deleted or modified while Git was using it
  2. A previous Git operation was interrupted or crashed during an index update
  3. Third-party tools that don't support split index modified repository files
  4. Concurrent Git processes caused a race condition updating the index
  5. File system corruption or synchronization issues (especially on network drives)
  6. Git version mismatch when different versions handle split index differently
  7. The splitIndex.sharedIndexExpire setting caused premature cleanup of a needed file

How to fix "error: split index base is outdated"

1Verify the error and check repository status

First, confirm the error and gather diagnostic information:

bash
# Try a simple Git command to reproduce the error
git status

# Check your current Git configuration for split index
git config --get core.splitIndex

# List files in .git directory to see index files
ls -la .git/index*
ls -la .git/sharedindex.*

If core.splitIndex returns true or you see sharedindex.* files, split index mode is active and likely causing the issue.

2Disable split index mode

The simplest fix is to disable split index mode, which consolidates the index back into a single file:

bash
# Disable split index and refresh the index
git update-index --no-split-index

This command:
1. Reads the current split index state
2. Merges all entries back into a single index file
3. Removes the dependency on the shared index file
4. Cleans up old shared index files

After running this, verify Git works:

bash
git status

If you still get errors, proceed to the next step.

3Force refresh the index

If the simple disable doesn't work, force a complete index refresh:

bash
# Really refresh the index and disable split index
git update-index --really-refresh --no-split-index

The --really-refresh flag forces Git to re-check all files against the working tree, rebuilding the index from scratch.

If that still fails, you may need to manually remove the corrupted index files:

bash
# Back up current index (optional, for recovery)
cp .git/index .git/index.backup

# Remove the index file
rm .git/index

# Remove shared index files
rm .git/sharedindex.*

# Reset the index from HEAD
git reset

This recreates a fresh index based on your last commit.

4Disable split index in configuration

To prevent the issue from recurring, disable split index in your Git configuration:

bash
# Disable for this repository only
git config core.splitIndex false

# Or disable globally for all repositories
git config --global core.splitIndex false

Also check and remove any system-level configuration:

bash
# Check where splitIndex is configured
git config --show-origin --get core.splitIndex

# If set at system level, disable it
git config --system core.splitIndex false

The split index feature is disabled by default in Git, so someone or something explicitly enabled it.

5Update Git to the latest version

Older Git versions had bugs in split index handling. Update to the latest version:

On Ubuntu/Debian:

bash
sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git

On macOS (using Homebrew):

bash
brew update
brew upgrade git

On Windows:
Download the latest installer from https://git-scm.com/download/win

After updating, verify the version:

bash
git --version

Then retry disabling split index:

bash
git update-index --no-split-index
6Re-enable split index (optional)

If you want to use split index for performance in large repositories, you can re-enable it after fixing the issue:

bash
# Re-enable split index
git update-index --split-index

# Configure it persistently
git config core.splitIndex true

When re-enabling, consider tuning related settings:

bash
# Control how often Git pushes changes back to shared index
# Default is 20% - higher values mean less frequent rewrites
git config splitIndex.maxPercentChange 20

# Control when old shared index files are deleted
# Default is "2.weeks.ago"
git config splitIndex.sharedIndexExpire "2.weeks.ago"

The split index provides performance benefits mainly for repositories with very large indexes (thousands of files). For most repositories, the overhead isn't worth the potential issues.

Advanced notes

Understanding Split Index Internals:

The split index feature was introduced to speed up Git operations on repositories with large indexes. Every Git command that reads or writes the staging area (index) must process the entire index file. For repositories with tens of thousands of files, this becomes a bottleneck.

How Split Index Works:

1. Git creates a "shared index" ($GIT_DIR/sharedindex.<SHA-1>) containing most entries
2. A smaller "split index" ($GIT_DIR/index) stores only recent changes
3. Operations that only touch recently-changed files are faster
4. Periodically, Git merges changes back into a new shared index

The index file contains a "link" extension pointing to the base shared index. When this link references a SHA-1 that doesn't match an existing sharedindex file, you get the "split index base is outdated" error.

Why Third-Party Tools Fail:

Many Git libraries don't fully support split index:
- libgit2 (used by many GUI tools): Limited split index support
- GitPython: May crash on split index repositories
- gitui: Explicitly doesn't support split index
- JGit (Java): Partial support

If you use such tools, avoid enabling split index.

Compatibility with Other Features:

Split index cannot be used with:
- Sparse index (core.sparseIndex): These features are mutually exclusive
- Some Git hooks that directly manipulate the index

CI/CD Considerations:

If you're seeing this error in CI/CD:
1. Clean the workspace before checkout
2. Don't persist .git between builds
3. Use GIT_TEST_SPLIT_INDEX=0 environment variable to disable
4. Consider using shallow clones which avoid index complexity

Diagnosing the Problem:

To see what Git thinks about your index:

bash
# Show index format version
git update-index --show-index-version

# View index entries (requires git-ls-files)
git ls-files --stage

Manual Recovery:

If nothing else works, you can recreate the repository state:

bash
# Save your work
git stash
git diff > uncommitted.patch

# Create fresh clone
cd ..
git clone <remote-url> repo-fixed
cd repo-fixed

# Re-apply your work
git stash pop  # If you had stashed changes
git apply uncommitted.patch  # If you had uncommitted changes

Performance Considerations:

The split index provides meaningful speedup only when:
- Your repository has 5000+ files in the index
- You frequently modify a small subset of files
- Your storage is slow (spinning disks, network drives)

For SSD storage and smaller repositories, split index adds complexity without significant benefit.

Frequently asked questions

What does "error: split index base is outdated" mean?
The "split index base is outdated" error indicates that Git's split index feature has encountered a synchronization problem between its two component files. The split index mode is an optimization that divides the Git index (staging area) into a base shared index file and a smaller split index file containing recent changes. <SHA-1> containing the bulk of entries - A split index file at $GIT_DIR/index containing only recent modifications This error appears when the split index file references a base (shared index) that no longer matches what's on disk.
How do I fix "error: split index base is outdated"?
This error occurs when Git's split index optimization becomes out of sync. The split index feature stores the index in two parts to speed up operations in large repositories. The fix involves disabling and optionally re-enabling the split index mode.
What causes "error: split index base is outdated"?
The shared index file was deleted or modified while Git was using it A previous Git operation was interrupted or crashed during an index update Third-party tools that don't support split index modified repository files
Is the "error: split index base is outdated" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading