Weblate Repository Sync Failures: Diagnostic Guide for Stale Pushes and Merge Alerts

When Weblate stops syncing with the VCS

A component that should be pulling and pushing translations quietly stops. The UI shows a repository alert banner, the pending outgoing changes counter stays non-zero, and new translations do not appear in the upstream repository. Sometimes the component appears locked for edits. The useful takeaway is that Weblate surfaces the underlying git error on the component's repository maintenance page, and the fix depends on that exact message plus the health of the Celery workers that execute VCS tasks.

Recognizable condition

• Alert banner on the component page: "Repository needs merge", "Push failed", or "Update failed".
• Translations made in Weblate do not reach the remote repository, or changes in the remote do not appear in Weblate.
• Pending outgoing changes count does not clear after a manual push.
• Component may be locked with a message about a repository problem.

Cause to symptom mapping

Ordered checks

1. Read the exact git error from the component

Open the component, then Manage > Repository maintenance, or the Alerts list. Weblate displays the underlying git error returned by the local clone. Record the full message before changing anything. This determines the fix path.

2. Confirm background workers are running

VCS operations run via Celery. On a self-hosted host with systemd, run as root or with sudo:

systemctl status weblate-celery-worker
systemctl status weblate-celery-beat

For Docker deployments, check containers are up:

docker ps | grep weblate

Look for a backed up queue and repeated task retries in the Weblate server log and Celery worker log. Stalled workers produce no VCS error in the UI, only silent queuing.

3. Verify repository credentials and URL

In the component settings check the Repository URL and Push URL. For SSH, the key must have write access to the remote branch. For HTTPS, the token must be valid and not read-only. Test connectivity from the Weblate host as the weblate user if possible, using the same key.

4. Check local disk and git state

Full disk prevents clones and commits. Check available space on the volume that holds Weblate's data directory, typically /var/lib/weblate or the Docker volume. Also note if the remote branch was force-pushed or rebased recently.

Fixes tied to findings

Credential failure

Rotate or re-grant the SSH key or token with write access. Update the Push URL in the component settings. Then trigger a manual push from Repository maintenance: Pull first to ensure local state is current, then Push. Verify the pending changes counter returns to zero and the alert clears.

Risk: an incorrect URL can cause repeated failures and fill the task queue.

Merge conflict or diverged history

Use Repository maintenance options. Merge attempts to reconcile Weblate's local commits with the remote. A Reset discards Weblate's local clone state and re-clones from the remote.

Caution: Reset discards uncommitted local changes. Always commit or export pending translations first via Repository maintenance > Export or by committing manually in the UI. Export creates a tarball of pending changes you can re-import after reset.

Stalled workers

Restart the Celery worker and beat services, then trigger Update/Pull and Push from Repository maintenance. Confirm tasks complete rather than retry indefinitely. Check worker logs for stack traces if the UI error is ambiguous.

Escalation criteria

• Multiple components fail simultaneously.
• Errors persist after credential update and a safe merge/reset.
• Logs show infrastructure issues: disk full, network timeouts, git version incompatibility.

Escalate to server-level debugging. For self-hosted instances, inspect Weblate server logs and Celery worker logs for stack traces. Hosted Weblate users cannot access server logs or Celery status and must rely on component-level diagnostics or support.

Verification

Reproduce the failure, read the exact git error on the repository maintenance page and match it to the cause table before applying any fix. After a fix, trigger Update/Pull then Push from repository maintenance and confirm the pending-changes counter returns to zero and the alert clears. Check that new commits appear in the remote repository and that changes pushed upstream are visible in Weblate after the next pull.

Limitations: exact menu names, alert wording, and available repository-maintenance actions vary between Weblate releases. Confirm against the version actually deployed. Reset and force-sync options change state and can lose uncommitted work if not exported first.