How to fix error: failed to configure maintenance schedule in Git

GitINTERMEDIATELOW

This error occurs when Git cannot set up automated maintenance tasks with your system scheduler. Git maintenance uses platform-specific schedulers (systemd, cron, launchctl, or schtasks) to run repository optimization tasks, and this fails when the scheduler is unavailable or lacks permissions.

What this error means

Git maintenance is a feature that automates repository optimization tasks like garbage collection, commit-graph updates, and loose object cleanup. When you run `git maintenance start`, Git attempts to register scheduled tasks with your operating system's task scheduler. This error indicates that Git could not successfully create or register these scheduled tasks with the system scheduler. The `git maintenance` command tries to use the most appropriate scheduler for your platform: systemd timers on modern Linux systems, cron on POSIX systems, launchctl on macOS, and Task Scheduler (schtasks) on Windows. The failure typically occurs when the scheduler is not installed, not running, or when Git lacks the necessary permissions to create scheduled tasks. This is a setup error rather than a runtime error - it prevents the automated maintenance from being scheduled but does not affect your ability to use Git normally or run maintenance manually.

How to fix "error: failed to configure maintenance schedule"

1Verify which scheduler Git is trying to use

Check what scheduler Git will attempt to use on your system:

bash

git maintenance start --scheduler=auto

For more control, explicitly specify the scheduler:

bash

# On Linux with systemd
git maintenance start --scheduler=systemd-timer

# On Linux/Unix with cron
git maintenance start --scheduler=crontab

# On macOS
git maintenance start --scheduler=launchctl

# On Windows
git maintenance start --scheduler=schtasks

This helps identify if the issue is with a specific scheduler.

2Check if the system scheduler is installed and running

Verify the scheduler service is available on your system.

For Linux with systemd:

bash

# Check if systemd user services are enabled
systemctl --user status

# List existing timers
systemctl --user list-timers

For cron:

bash

# Check if cron is installed
which cron || which crond

# Check if cron service is running
systemctl status cron  # Debian/Ubuntu
systemctl status crond # RHEL/CentOS

# Verify you can access crontab
crontab -l

For Windows:
Open Task Scheduler (taskschd.msc) and verify the service is running.

For macOS:

bash

# Check launchctl status
launchctl list | grep git

3Install missing scheduler if needed

If the scheduler is not installed, install it using your package manager.

Debian/Ubuntu:

bash

sudo apt update
sudo apt install cron
sudo systemctl enable --now cron

RHEL/CentOS/Fedora:

bash

sudo dnf install cronie
sudo systemctl enable --now crond

Arch Linux:

bash

sudo pacman -S cronie
sudo systemctl enable --now cronie

For systemd-based systems, ensure user services are enabled:

bash

systemctl --user enable --now systemd-tmpfiles-setup.service

4Check crontab permissions

Verify you have permission to create crontab entries:

bash

# Check if cron.deny exists and contains your username
cat /etc/cron.deny 2>/dev/null | grep $(whoami)

# Check if cron.allow exists (if it does, your user must be listed)
ls -la /etc/cron.allow

If you are blocked by cron.deny, ask your system administrator to remove the restriction, or add your user to cron.allow:

bash

echo "$(whoami)" | sudo tee -a /etc/cron.allow

5Enable systemd user services for lingering

On systemd-based Linux systems, enable user service lingering so timers persist after logout:

bash

# Enable lingering for your user
sudo loginctl enable-linger $(whoami)

# Verify lingering is enabled
loginctl show-user $(whoami) | grep Linger

Then try setting up maintenance again:

bash

git maintenance start --scheduler=systemd-timer

6Remove existing maintenance schedule and retry

Clear any partial or corrupted maintenance configuration:

bash

# Stop and unregister maintenance
git maintenance unregister --force
git maintenance stop

# Remove maintenance config
git config --unset maintenance.strategy
git config --unset maintenance.auto

# For systemd, manually remove timer units if they exist
rm -f ~/.config/systemd/user/git-maintenance@*.timer
rm -f ~/.config/systemd/user/git-maintenance@*.service
systemctl --user daemon-reload

# For cron, manually remove entries
crontab -l | grep -v git-maintenance | crontab -

# Try again
git maintenance start

7Run maintenance manually if scheduling fails

If you cannot resolve the scheduler issue, you can still benefit from maintenance by running it manually:

bash

# Run all maintenance tasks now
git maintenance run

# Run specific tasks
git maintenance run --task=gc
git maintenance run --task=commit-graph
git maintenance run --task=prefetch

You can create your own scheduled task using your preferred method (cron, systemd timer, Task Scheduler) to run git maintenance run periodically.

How to fix error: failed to configure maintenance schedule in Git

What this error means

Typical symptoms

Common causes

How to fix "error: failed to configure maintenance schedule"

Advanced notes

Related errors

Official resources & further reading