Diagnosing Weblate Git Sync Failures in Self-Hosted Deployments

Recognizable Condition

Weblate's component dashboard displays Repository push failed or Repository pull failed alerts. Translation changes made in Weblate do not appear in the upstream Git repository, or commits pushed directly to the remote are not reflected in Weblate.

Cause and Diagnostic Quick Reference

Symptom	Likely Cause	Primary Diagnostic Command
Non‑fast‑forward push rejected	Diverged history (local and remote branches have different commits)	git log --oneline -10 on the container's repo
Authentication failure	Expired SSH key, revoked personal access token, or mis‑configured credential store	ssh -T [contact removed] (or provider equivalent) from the Weblate container
Missing remote branch	Component configured for a branch that does not exist on the remote	git ls-remote origin
Remote hook rejection	Branch protection rules blocking Weblate's bot user (e.g., require PR, signed commits)	Check remote provider's branch protection settings and webhook delivery logs
Lock timeout	Concurrent Celery workers or git gc holding /app/data/vcs/*/lock	ls -la /app/data/vcs/ and ps aux | grep git
Merge conflict	Upstream changes conflict with Weblate's pending commits	git status in the component repo
Submodule failure	Submodules not initialized or updated	git submodule status
Git LFS quota exceeded	Large files tracked by LFS but LFS not installed or quota full	git lfs ls-files
Webhook misconfiguration	Secret rotated in Weblate but not updated on remote, or URL incorrect	Inspect remote repository's webhook delivery history
API rate limit	Provider limits (GitHub 5 000 req/hr per token, GitLab 600 req/min) exceeded	Check response headers X-RateLimit-Remaining or provider dashboard

Ordered Diagnostic Checks

1. Component Repository status – Open the component in Weblate UI; note the exact error message and timestamp.
2. Test connectivity from the container – Run docker exec weblate ssh -T [contact removed] (or HTTPS curl -I https://github.com) to verify credentials and network reachability.
3. Inspect the on‑disk repository – docker exec weblate git -C /app/data/vcs/ status. Look for uncommitted changes, detached HEAD, or lock files.
4. Verify remote branch existence – docker exec weblate git -C /app/data/vcs/ ls-remote origin. Confirm the branch name matches the component's Repository branch setting.
5. Review Weblate logs – docker logs weblate | grep -i -e push -e pull -e vcs. Correlate timestamps with the UI alert.
6. Check Celery beat/task logs – If Flower is enabled, inspect the vcs.pull and vcs.push task results; otherwise check docker logs weblate-celery.
7. Validate credential store – In Weblate admin (/admin/), verify the SSH key or token stored for the component's remote is current and has the required scopes.
8. Look for stale lock files – docker exec weblate find /app/data/vcs -name 'lock' -type f. Remove any lock older than the last sync interval if no git process is running.

Fixes Mapped to Findings

Non‑fast‑forward (diverged history)

Use Weblate's Reset repository button (Component → Repository → Reset) to force the local clone to match the remote. Alternatively, from the container: docker exec weblate git -C /app/data/vcs/ push --force-with-lease origin . Risk: force‑push rewrites remote history; ensure you have a recent backup of the remote branch.

Authentication failure

Regenerate the SSH key or personal access token on the Git provider, then update the credential in Weblate admin. For SSH, ensure the private key is stored without a passphrase (Weblate cannot prompt).

Missing remote branch

Either create the branch on the remote (git push origin ) or change the component's Repository branch setting to an existing branch.

Remote hook rejection (branch protection)

On GitHub/GitLab, add the Weblate bot user to Allow force pushes or Bypass pull request requirements for the protected branch. If signed commits are required, configure GPG signing in Weblate (Component → Repository → GPG key).

Lock timeout

Reduce Celery concurrency (CELERY_WORKER_CONCURRENCY env var) to avoid simultaneous git operations. Disable automatic git gc in the container (git config --global gc.auto 0) or schedule it outside sync windows.

Merge conflicts

Use Weblate's Resolve conflicts UI action, or manually abort the merge in the container: docker exec weblate git -C /app/data/vcs/ merge --abort, then trigger a fresh pull.

Submodule issues

Enable Initialize submodules in the component's repository settings. Then run docker exec weblate git -C /app/data/vcs/ submodule update --init --recursive.

Git LFS quota

Install git-lfs in the container (Alpine: apk add git-lfs; Debian/Ubuntu: apt-get install git-lfs). Run git lfs install once per repository. Verify quota on the provider and purge unused LFS objects if needed.

Webhook misconfiguration

Regenerate the webhook secret in Weblate (Component → Repository → Webhook secret), then immediately update the webhook URL and secret on the remote repository's settings. Old deliveries will fail until the secret matches.

API rate limit

Increase SYNC_INTERVAL (default 300 s) to reduce polling frequency. Use a dedicated token with higher quota (GitHub Apps, GitLab personal access token with api scope). Enable Lazy commits (Component → Repository → Lazy commits) to batch changes.

Escalation Criteria

1. Force‑push is required but no recent backup of the remote branch exists (data‑loss risk).
2. Credentials appear compromised – rotate immediately and audit access logs.
3. Failures persist after applying the above fixes (indicates deeper configuration or infrastructure issue).
4. Multiple components fail simultaneously, suggesting a shared resource problem (e.g., database, Celery broker).
5. Compliance mandates signed commits but GPG signing cannot be configured in Weblate.

When escalating, provide: Weblate version (weblate --version), component export (weblate dumpdata), sanitized logs, remote provider name, and steps already attempted.

Verification After Fix

1. Trigger a manual sync: Component → Repository → Pull then Push – both should show green checkmarks.
2. Make a test translation change in Weblate UI; verify the commit appears in the remote repository within SYNC_INTERVAL.
3. Push a commit directly to the remote branch; confirm Weblate pulls it and updates translations.
4. Check webhook delivery: remote repository's webhook UI should show 200 OK for recent ping/push events.
5. Run docker exec weblate weblate checkgit --all – should report no errors.
6. Monitor Celery Flower (if enabled) for successful vcs.pull and vcs.push task completion.

Limitations and Version Notes

• Weblate 5.x switched the default VCS backend from GitPython to dulwich for some operations; the Reset repository behavior may differ between versions.
• Docker deployments must mount /app/data persistently; ephemeral storage loses repository state on container restart.
• Git LFS requires git-lfs >= 3.0 in the container; Alpine images need apk add git-lfs, not apt.
• Branch protection rules on GitHub/GitLab often block the Weblate bot unless explicitly allowed.
• Webhook secret rotation invalidates existing deliveries; update the remote webhook immediately after regenerating in Weblate.
• Rate limits vary by provider and may be shared across runners or apps using the same token.