How to fix error: maintenance gc task failed in Git

GitINTERMEDIATEMEDIUMUpdated Dec 2, 2025· 176 views

Git maintenance gc task failed when attempting to clean up and optimize your repository. This usually occurs due to file locks, permission issues, or corrupted objects preventing garbage collection from completing.

Quick fix

Fixes error: maintenance gc task failed

cat .git/gc.log
  1. Check for gc.log file and review the error
  2. Close programs that might lock Git files
  3. Check and fix repository permissions
  4. Run repository integrity check
git — error
cat .git/gc.log
error: maintenance gc task failed

What this error means

Git garbage collection (gc) is a maintenance task that cleans up unnecessary files and optimizes your repository for better performance. The "maintenance gc task failed" error indicates that Git was unable to complete this optimization process. This error commonly appears during automatic maintenance operations (triggered by git maintenance run --auto or older git gc --auto commands) or when explicitly running git maintenance run --task=gc. Git performs garbage collection to remove unreachable objects, repack files for efficiency, and reduce disk space usage. The failure can stem from various sources including file system locks (especially on Windows with IDEs or Git GUI tools running), permission issues preventing Git from modifying repository files, insufficient disk space, or corrupted objects in the repository. When gc fails, Git creates a gc.log file that blocks future automatic cleanup attempts until the underlying issue is resolved.

Typical symptoms

  • Push or pull operations show "maintenance gc task failed" warning
  • Repository size grows larger than expected over time
  • Automatic garbage collection stops working
  • A gc.log file appears in the .git directory
  • Git operations become slower due to fragmented repository
  • Windows processes like TortoiseGit, Visual Studio, or IISExpress lock repository files

Common causes

  1. File locking by IDE or Git GUI tools (TortoiseGit, Visual Studio, Eclipse with EGit)
  2. Existing gc.log file blocking automatic garbage collection
  3. Insufficient file permissions to modify .git directory
  4. Corrupted objects in the repository database
  5. Insufficient disk space for repacking operations
  6. Concurrent Git operations interfering with garbage collection
  7. Memory limits exceeded on large repositories (especially on Windows)
  8. Dangling or unreachable objects causing cleanup failures

How to fix "error: maintenance gc task failed"

1Check for gc.log file and review the error

First, check if a gc.log file exists that might be blocking automatic garbage collection:

bash
cat .git/gc.log

Review the error message to understand what went wrong. If the issue has been resolved, delete the gc.log file:

bash
rm .git/gc.log

This will allow automatic garbage collection to run again on future operations.

2Close programs that might lock Git files

On Windows, close any programs that might have locks on repository files:

- Close Visual Studio, VS Code, or other IDEs
- Exit TortoiseGit or other Git GUI tools
- Stop IISExpress or local development servers
- Close file explorers browsing the repository

After closing these programs, try running garbage collection again:

bash
git maintenance run --task=gc

Or with the older command:

bash
git gc
3Check and fix repository permissions

Verify that you have proper permissions on the .git directory:

bash
ls -la .git

If permissions are incorrect, fix them (Linux/macOS):

bash
chmod -R 755 .git
chown -R $(whoami) .git

On Windows, right-click the .git folder, select Properties > Security, and ensure your user account has Full Control.

4Run repository integrity check

Check for corrupted objects in your repository:

bash
git fsck --full

Check the count of loose objects:

bash
git count-objects -v

If corrupted objects are found, you may need to recover from a backup or clone the repository fresh and copy your working directory changes.

5Enable debug logging to identify the issue

Run garbage collection with debug logging to see detailed error output:

bash
GIT_TRACE=1 git maintenance run --task=gc

Or capture errors to a file:

bash
git gc 2> gc_error.log
cat gc_error.log

This will help identify the specific cause of the failure.

6Force garbage collection with aggressive options

If normal garbage collection fails, try forcing it with more aggressive options:

bash
git gc --aggressive --prune=now

This tells Git to:
- Use more aggressive optimization (slower but more thorough)
- Immediately prune all dangling commits instead of waiting 2 weeks

Note: This operation can take significant time on large repositories.

7Clean up manually if gc continues to fail

If automated gc fails, try manual cleanup steps:

First, repack the repository:

bash
git repack -adf

Then prune loose objects:

bash
git prune

Finally, refresh the index:

bash
git update-index --refresh

Advanced notes

git maintenance vs git gc: Modern Git (2.31+) introduced the git maintenance command as a replacement for git gc. The maintenance command provides better control and should not be mixed with git gc. If you're using git maintenance, avoid running git gc directly.

Disabling automatic gc: You can disable automatic garbage collection with git config --global gc.auto 0, but this is not recommended as it will cause repository size to grow and slow down operations over time. Only use this as a temporary workaround.

Large repositories: Repositories with large binary files or extensive history may experience slow or failing gc operations. Consider using Git LFS (Large File Storage) for binary files or tools like git-annex for very large files.

Memory limits on Windows: Git gc may hit the 4GB memory limit on Windows systems. Using git config gc.pruneExpire "2 weeks ago" can help by spreading the work across multiple gc runs.

Concurrent operations: Git gc running concurrently with other Git operations can cause failures or even repository corruption. The git maintenance command handles locking more safely.

Pack redundancy: After a failed gc, redundant packs may accumulate. Use git pack-redundant --all | xargs rm to identify and remove them, but be cautious as this command is considered experimental.

As a last resort: If the repository is severely corrupted and gc cannot be fixed, clone the repository fresh and copy the .git folder to your working directory, or simply reclone and migrate your uncommitted changes.

Frequently asked questions

What does "error: maintenance gc task failed" mean?
Git garbage collection (gc) is a maintenance task that cleans up unnecessary files and optimizes your repository for better performance. The "maintenance gc task failed" error indicates that Git was unable to complete this optimization process. This error commonly appears during automatic maintenance operations (triggered by git maintenance run --auto or older git gc --auto commands) or when explicitly running git maintenance run --task=gc.
How do I fix "error: maintenance gc task failed"?
Git maintenance gc task failed when attempting to clean up and optimize your repository. This usually occurs due to file locks, permission issues, or corrupted objects preventing garbage collection from completing.
What causes "error: maintenance gc task failed"?
File locking by IDE or Git GUI tools (TortoiseGit, Visual Studio, Eclipse with EGit) Existing gc.log file blocking automatic garbage collection Insufficient file permissions to modify .git directory
Is the "error: maintenance gc task failed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading