Diagnosing Weblate VCS Synchronization Failures in 4.x

Recognizable condition

When Weblate stops pulling upstream changes or pushing translated strings, the dashboard shows indicators such as a stagnant 'Last update' timestamp, an orange or red status badge with 'Error' or 'Offline', or push attempts returning authentication errors like Permission denied (publickey) or HTTP 403 Forbidden. These symptoms may appear individually or together, depending on whether the failure is read-only (pull) or write-only (push).

Diagnostic table: symptoms vs likely causes

Symptom	Possible cause
Translations stale, 'Last update' unchanged	Weblate cannot reach the repository or credentials have expired
Push fails with 'Permission denied (publickey)'	SSH key not registered with the hosting service or not accessible to the Weblate process
Push fails with 'HTTP 403 Forbidden'	Personal access token expired, revoked, or missing required scopes
Component shows 'Offline' or 'Error'	Webhook disabled, misconfigured, or repository path permissions incorrect

Ordered diagnostic checks

1. Verify the repository URL and credentials in the Weblate component configuration.

   From the Weblate admin interface, navigate to Management → Components → component → Repository. Confirm that the URL, authentication type (SSH/HTTP), and credentials are correct. If using SSH, note the SSH key fingerprint displayed by Weblate.

   $ sudo -u weblate bash -c 'cd /app/data/vcs/ && git remote -v'

   Replace with the component's URL‑safe slug. Required permission: the weblate user must be able to read the SSH private key or HTTP token stored in the Weblate data directory. Expected check: the command lists the remote URLs without prompting for a password or failing with a key‑rejection error. Risk: if the command fails, credentials or file permissions are misconfigured; do not attempt a push until this is resolved.

2. Test the specific VCS operation that is failing.

   • For pull failures: run git fetch origin from the component directory as the weblate user.
   • For push failures: attempt git push origin main (or the default branch) and capture the full error message.

   $ sudo -u weblate bash -c 'cd /app/data/vcs/ && git fetch origin'

   If this succeeds, Weblate should be able to perform the same operation automatically. If it fails with the same error you see in the Weblate interface, the root cause is credential or permission related.

3. Check Weblate logs for VCS‑related messages.

   Examine the container or log file (e.g., /app/log/weblate.log or the journal output if running via systemd). Look for entries containing 'Repository clone failed', 'SSH key rejected', or 'HTTP 403'. The absence of recent such messages after a manual sync often indicates the issue was transient or resolved by the previous steps.

4. Confirm repository directory permissions.

   Weblate requires write access to the VCS checkout directory to perform pushes and updates. On the server, verify that the weblate user (or the user under which the Weblate process runs) owns or has at least read‑write permission on /app/data/vcs/. A quick check:

   $ ls -ld /app/data/vcs/

   Expected: the directory is owned by weblate or a group that the weblate user can read/write. If the directory is owned by root or a different user without explicit permission grants, Weblate may silently fail clone or pull operations.

5. Review webhook configuration (if automatic synchronization is expected).

   Weblate can be configured to trigger a VCS update when the upstream repository receives a push via a webhook. In the component settings, ensure the webhook URL is reachable and, if a secret is set, that it matches the secret configured in your hosting service (GitHub, GitLab, Bitbucket, etc.). If webhooks are disabled or the URL is incorrect, Weblate will not receive push notifications and will rely on the periodic Celery task interval (default ~2 minutes) to detect changes.

6. Inspect Celery worker status and task execution.

   VCS update tasks in Weblate are processed by Celery. If the server is under high load or the number of Celery workers is insufficient, the VCS update task may time out before completing. In the Weblate admin interface, go to Management → Background tasks and verify that the most recent VCS update task completed without error. If many tasks are pending or stuck, consider increasing the number of Celery workers or adjusting the component's timeout settings.

Fixes tied to findings

• If step 1 revealed incorrect or expired credentials: generate a new SSH key pair or personal access token with the appropriate scopes, add the public key to your hosting service, and update the Weblate component's credentials. For SSH keys, ensure the private key is placed where the weblate user can access it (typically a path configured in Weblate's settings.py or via the UI).
• If step 2 failed with the same error as in the interface: the diagnostic pinpointed the exact failure. Apply the corresponding fix from this list, then trigger a manual sync from the Weblate interface (Management → Components → component → Repository → Save) to force an immediate VCS update.
• If step 3 showed recent 'Repository clone failed' messages but steps 1 and 2 passed: the issue may be network‑level (firewall, DNS resolution). Verify that the server can resolve the hosting service's hostname and that outbound HTTPS/Ssh ports are not blocked.
• If step 4 revealed permission problems: adjust the ownership or ACLs of the VCS directory so the Weblate process user can write. Example: $ chown -R weblate:weblate /app/data/vcs/. Then run a manual fetch to confirm the fix.
• If step 5 indicated a webhook mismatch: update the webhook secret in both Weblate and your hosting service, or disable webhook‑driven sync and rely on the scheduled Celery task instead.
• If step 6 showed Celery backlog or timeouts: scale the Celery deployment (add workers, increase concurrency) or raise the component's timeout setting in the Weblate interface to allow longer VCS operations under load.

Escalation criteria

If you have completed all ordered checks, applied the appropriate fixes, and Weblate still reports synchronization failures or the component remains offline, consider the following escalation paths:

• Verify with your hosting service that the repository URL, SSH key, or token is valid from an external perspective. Some services restrict API access by IP range or require additional registration of deploy keys.
• Check whether the repository is private and if access restrictions (such as branch protection rules or required review status) are preventing Weblate from pushing. Weblate can push to protected branches only if the configured credential has merge rights.
• Contact Weblate support or consult the mailing list, providing the full Weblate log excerpt (last 50 lines), the component configuration (URL, authentication type, webhook settings), and the output of the manual git commands you ran. This information helps maintainers distinguish between Weblate‑side configuration issues and upstream infrastructure problems.
• If your deployment uses a reverse proxy or firewall in front of Weblate, confirm that Weblate can outbound‑connect to the hosting service on port 22 (SSH) and port 443 (HTTPS). Misconfigured proxy exceptions can cause silent connection failures.