How to fix error: repository not registered for maintenance in Git

GitBEGINNERLOWUpdated Dec 2, 2025· 102 views

This error appears when trying to unregister or stop background maintenance on a repository that was never registered with the Git maintenance scheduler in the first place.

Quick fix

Fixes error: repository not registered for maintenance

git config --global --get-all maintenance.repo
  1. Check current maintenance registration status
  2. Use --force flag to suppress the error
  3. Register the repository first if maintenance is desired
  4. Manually remove stale entries from global config
git — error
git config --global --get-all maintenance.repo
error: repository not registered for maintenance

What this error means

This error occurs when you attempt to run `git maintenance unregister` or `git maintenance stop` on a repository that is not currently registered for background maintenance tasks. Git's maintenance system tracks which repositories should receive automatic optimization through a global configuration list (maintenance.repo), and this error indicates the current repository is not in that list. The Git maintenance feature, introduced in Git 2.30, allows repositories to be registered for automatic background tasks like garbage collection, commit-graph updates, and prefetching. When registered via `git maintenance start` or `git maintenance register`, the repository is added to your user's global Git config and scheduled tasks are created using your system's scheduler (systemd timers on Linux, launchd on macOS, Task Scheduler on Windows, or cron as a fallback). This error is informational rather than critical - it simply confirms that the repository wasn't set up for automated maintenance. It commonly appears when cleaning up repositories, running unregister commands in scripts without checking registration status first, or when users mistakenly think a repository had background maintenance enabled.

Typical symptoms

  • Error message "repository not registered for maintenance" when running git maintenance unregister
  • git maintenance stop command fails with registration error
  • Unable to remove repository from background maintenance schedule
  • Scripts or cleanup commands fail when attempting to unregister maintenance

Common causes

  1. Repository was never registered with git maintenance register or git maintenance start
  2. Repository was already unregistered in a previous operation
  3. Running unregister command in wrong directory (not in a Git repository)
  4. Global Git config does not contain this repository in maintenance.repo list
  5. Attempting to unregister after repository was moved or deleted from original location

How to fix "error: repository not registered for maintenance"

1Check current maintenance registration status

First, verify if the repository is registered for maintenance by checking your global Git configuration:

bash
git config --global --get-all maintenance.repo

This will list all repositories currently registered. If your repository path is not in the output, it's not registered.

You can also check if scheduled tasks are running:

Linux (systemd):

bash
systemctl --user list-timers | grep git-maintenance

macOS (launchd):

bash
launchctl list | grep org.git-scm.git

Windows (Task Scheduler):

powershell
schtasks /query | findstr git-maintenance
2Use --force flag to suppress the error

If you're running an unregister command in a script or automation and don't care whether the repository was registered, use the --force flag:

bash
git maintenance unregister --force

This will return success even if the repository is not registered, making it safe for idempotent cleanup scripts.

3Register the repository first if maintenance is desired

If you actually want background maintenance enabled for this repository, register it:

bash
git maintenance start

This will:
- Add the repository to maintenance.repo in your global config
- Create scheduled tasks on your system
- Run hourly, daily, and weekly maintenance tasks automatically

Alternatively, use git maintenance register if you want to register without immediately starting the scheduler.

4Manually remove stale entries from global config

If you've moved or deleted repositories and want to clean up the maintenance.repo list, edit your global config:

bash
git config --global --edit

Look for lines like:

ini
[maintenance]
  repo = /path/to/old/repo1
  repo = /path/to/old/repo2

Remove entries for repositories that no longer exist or should not be maintained. You can also remove specific entries with:

bash
git config --global --unset-all maintenance.repo /path/to/old/repo

Advanced notes

Platform-Specific Scheduler Details:

Git maintenance uses different scheduling systems depending on your platform. On Linux, it prefers systemd user timers (if available) over cron. On macOS, it uses launchd agents via .plist files. On Windows, it uses Task Scheduler via schtasks. The scheduler runs git maintenance run --scheduled hourly, with daily tasks at midnight and weekly tasks at midnight on the first day of the week.

Configuration Side Effects:

When you run git maintenance register, Git automatically sets maintenance.auto = false in the repository's local config. This disables foreground maintenance (like automatic gc during git commands) to prevent conflicts with background maintenance. This setting persists even after unregistering, so you may want to manually re-enable it with git config --unset maintenance.auto if you unregister a repository.

Lock File Behavior:

Each maintenance run takes a lock at .git/maintenance.lock to prevent concurrent executions that could corrupt the repository. If you see lock file errors, another maintenance process may be running, or a stale lock file exists from a crashed process. In Git 2.48+, maintenance provides better hints about these situations.

Conflict with git gc:

Do not run git gc manually on repositories registered for maintenance. The git gc command does not respect the object database lock used by git maintenance, which can lead to race conditions and repository corruption. Use git maintenance run instead for manual maintenance on registered repositories.

No Automatic Cleanup:

There is no automated way to unregister repositories when they're deleted or moved. You should periodically review your maintenance.repo list and clean up stale entries manually to avoid scheduler overhead from attempting maintenance on non-existent repositories.

Frequently asked questions

What does "error: repository not registered for maintenance" mean?
This error occurs when you attempt to run git maintenance unregister or git maintenance stop on a repository that is not currently registered for background maintenance tasks. repo), and this error indicates the current repository is not in that list. 30, allows repositories to be registered for automatic background tasks like garbage collection, commit-graph updates, and prefetching.
How do I fix "error: repository not registered for maintenance"?
This error appears when trying to unregister or stop background maintenance on a repository that was never registered with the Git maintenance scheduler in the first place.
What causes "error: repository not registered for maintenance"?
Repository was never registered with git maintenance register or git maintenance start Repository was already unregistered in a previous operation Running unregister command in wrong directory (not in a Git repository)
Is the "error: repository not registered for maintenance" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading