How to Fix the ownCloud File Locking “Lock Mechanism Timeout” Error

If ownCloud reports a file locking timeout during sync, upload, move, rename, or chunk assembly, the first thing to know is that the error usually involves transactional file locking, not the user-facing Manual File Locking feature. Transactional locking is an internal safety mechanism that prevents two requests from saving or mutating the same file at the same time. It is enabled by default in ownCloud and can use the database or Redis as its locking backend.

Current ownCloud 11 documentation still recommends Redis for transactional file locking because database-backed locks create significant database load. On clustered installations, every application node must use the same shared Redis instance for locking. That is the durable fix to understand before changing timeout values or deleting lock records.

This guide walks through the problem from a beginner administrator's perspective: what the lock means, what to back up, how to confirm the failing component, how to configure Redis, how clusters change the picture, and which shortcuts can make the situation worse.

What the error means

When ownCloud changes a file, it acquires a lock so another request cannot perform an incompatible change at the same time. The lock can also cover a parent directory so it cannot be renamed while work is happening inside it. If the lock cannot be acquired in time, the operation can fail with a locked-resource or timeout-style error rather than risking a corrupted file.

According to the ownCloud 11 transactional file locking documentation, this mechanism also handles interrupted uploads, shared files, external storage, and encrypted files.

This is different from Manual File Locking, the optional WebDAV-based check-in/check-out feature that lets a user deliberately lock a file in the web interface. Manual locks have configurable user-facing expiration values. Changing those values does not fix a transactional lock backend that is overloaded or incorrectly configured.

Before you start

• Back up the ownCloud database and config/config.php.
• Record your ownCloud version and deployment type: traditional package, Docker Compose, or multi-node cluster.
• Identify your database engine and whether Redis is already installed.
• Record the exact operation that fails, such as a desktop sync, WebDAV upload, folder rename, or chunked upload.
• Note whether the problem affects one file, one user, or many users at the same time.

A broad outage affecting many users usually points to a shared component such as the lock backend, database, Redis, or storage. A repeatable error on one file may instead involve a genuinely active operation or a stale lock that has not yet expired.

Step 1: Confirm which locking mechanism is failing

Start with the ownCloud log, web server log, PHP-FPM log, and Redis service status. You are looking for repeated locked-resource exceptions, database lock-wait errors, Redis connection failures, or a pattern where the same path remains blocked long after the original operation ended.

Useful checks on a Linux host include:

systemctl status redis-server
redis-cli PING
ps -ef | grep php
tail -n 200 /path/to/owncloud/data/owncloud.log

A healthy Redis command should return PONG. If ownCloud is configured to reach Redis through a socket, container hostname, password, or remote host, test the same connection path ownCloud actually uses rather than assuming that a local redis-cli test proves application connectivity.

If the log contains a database message similar to “lock wait timeout exceeded,” investigate database contention as well. The old database locking backend is functional, but ownCloud's documentation explicitly warns that it places significant load on the database.

Step 2: Move transactional file locking to Redis

For a traditional ownCloud installation, configure Redis as the memcache.locking backend in config/config.php. The current ownCloud memory caching documentation provides a Redis TCP example similar to this:

'filelocking.enabled' => true,
'memcache.locking' => '\OC\Memcache\Redis',
'redis' => [
    'host' => 'localhost',
    'port' => 6379,
    'timeout' => 0,
    'password' => '',
],

Do not copy the empty password literally into an Internet-exposed Redis setup. The ownCloud memory caching documentation recommends protecting Redis appropriately. Ideally, Redis should be reachable only from trusted ownCloud hosts or the internal container network.

In the official ownCloud Docker configuration, Redis is enabled with environment variables. Current ownCloud 11 documentation shows:

OWNCLOUD_REDIS_ENABLED=true
OWNCLOUD_REDIS_HOST=redis
OWNCLOUD_REDIS_PORT=6379

When Redis is enabled in that deployment model, ownCloud sets both the distributed cache and locking cache to Redis automatically. Use the deployment-specific configuration documented for your installation instead of mixing Docker environment variables with a manually maintained config.php unless you understand which layer wins.

Step 3: In a cluster, make every node use the same Redis

A cluster is a deployment with multiple ownCloud application servers behind a load balancer. In this design, a lock created on one application node must be visible to every other node. Per-node APCu caches or separate per-node Redis instances cannot provide that shared lock state.

Le guide d'ownCloud relatif au stockage partagé en cluster est clair : utilisez une instance Redis partagée accessible par tous les nœuds de l'application. Il déconseille fortement de s'appuyer sur le système de fichiers ou les verrous NFS pour le verrouillage applicatif d'ownCloud.

Vérifiez que chaque nœud utilise le même point de terminaison Redis et les mêmes identifiants. Un problème fréquent survient lorsqu'un nœud utilise encore la base de données ou une instance Redis locale, tandis que les autres utilisent le service partagé. Cela engendre un comportement de verrouillage incohérent, pouvant paraître intermittent, car le résultat dépend du nœud d'application qui traite chaque requête.

Étape 4 : Vérifiez la configuration et réessayez l’opération initiale.

Après avoir configuré Redis, vérifiez les paramètres ownCloud actifs occ. Selon votre installation, cette commande peut être exécutée en tant qu'utilisateur du serveur web ou via Docker Compose.

sudo -u www-data php occ config:system:get memcache.locking
sudo -u www-data php occ config:system:get filelocking.enabled

La première commande devrait renvoyer un résultat \OC\Memcache\Redis, et le verrouillage transactionnel des fichiers devrait rester activé. Ne « résolvez » pas le problème en désactivant le verrouillage des fichiers. Cela supprimerait une protection de l'intégrité des données au lieu de corriger le système sous-jacent.

Réessayez maintenant l'opération qui a échoué. Si le chargement d'un fichier depuis un client de bureau a expiré, répétez-le. Si le déplacement d'un dossier a échoué, répétez-le. Surveillez les journaux ownCloud et Redis pendant le test. Une nouvelle tentative réussie, sans expiration de délai récurrente, constitue une preuve bien plus convaincante que l'exécution d'une commande de maintenance sans rapport avec le problème.

Que faire si le fichier apparaît toujours verrouillé ?

Vérifiez d'abord si une autre opération utilise réellement le fichier. Les chargements volumineux, les accès au stockage externe, les déplacements de fichiers, le chiffrement ou un stockage lent peuvent légitimement maintenir le verrou plus longtemps que prévu. Supprimer le verrou pendant qu'une opération est encore active peut créer la condition de concurrence que le verrou est censé empêcher.

Les verrous transactionnels sont conçus pour être libérés après l'interruption d'une transaction. La documentation de configuration d'ownCloud, bien qu'ancienne, décrit également un mécanisme de durée de vie des verrous (TTL) permettant leur suppression automatique. Les détails de configuration exacts pouvant varier selon la version d'ownCloud, vérifiez l'option correspondante dans la documentation avant toute modification. Évitez de définir une durée de vie extrêmement courte pour masquer un problème de lenteur du stockage ou de la base de données.

Si les métadonnées sont incohérentes, ownCloud propose des commandes d'analyse de fichiers à visée réparatrice. La documentation officielle de la commande occ recommande de sauvegarder la base de données avant une analyse de réparation. Cette analyse est destinée aux métadonnées de fichiers endommagées ou incohérentes ; elle ne constitue pas une solution de première intention aux conflits de verrouillage classiques.

Ne confondez pas le verrouillage transactionnel avec le verrouillage manuel des fichiers.

La documentation actuelle d'ownCloud 11 indique que le verrouillage manuel des fichiers est désactivé par défaut dans l'interface web. Lorsqu'il est activé, la durée de verrouillage par défaut est de 30 minutes, avec une durée maximale de 24 heures. Ces valeurs sont détaillées dans le guide du verrouillage manuel des fichiers .

Si votre problème concerne spécifiquement un verrou manuel créé par l'utilisateur, alors des commandes comme celles-ci sont pertinentes :

docker compose exec owncloud occ config:app:set files lock_timeout_default --value 1800
docker compose exec owncloud occ config:app:set files lock_timeout_max --value 86400

Si votre problème est un délai d'attente interne lors de la synchronisation ou de l'enregistrement d'un fichier, modifier ces valeurs de verrouillage manuel n'est généralement pas la solution.

Erreurs courantes qui aggravent les délais d'expiration des verrous

Suppression des lignes verrouillées de la base de données pendant que ownCloud est actif

Cela peut entrer en conflit avec les requêtes en cours et supprimer des verrous valides. De plus, cela ne fait que masquer le symptôme sans corriger la base de données ni la configuration Redis à l'origine du délai d'attente.

Désactivation du verrouillage des fichiers transactionnels

Le verrouillage transactionnel sert à protéger les opérations sur les fichiers contre les modifications simultanées. Laissez-le activé et réparez le système.

Utilisation d'APCu pour le verrouillage partagé dans un cluster

APCu est un cache local, propre à chaque nœud. Il convient à la mise en cache locale, mais ne fournit pas d'état de verrouillage partagé entre plusieurs serveurs d'applications. Utilisez un Redis partagé pour les caches distribués et verrouillables dans les déploiements en cluster.

Exécuter une instance Redis par nœud d'application

Chaque serveur a donc une vision différente des verrous de fichiers. Tous les nœuds ont besoin du même service Redis partagé pour la coordination des verrous.

Augmenter le temps d'attente de verrouillage de la base de données sans corriger les conflits

Un délai d'expiration de la base de données plus long risque d'allonger l'attente des utilisateurs. Déplacer le trafic de verrouillage transactionnel vers Redis réduit la charge de travail de verrouillage de la base de données et résout le problème de goulot d'étranglement architectural.

Rendre la durée d'expiration du verrou irréaliste et trop courte

Une opération de stockage externe lente ou un chargement important peuvent légitimement nécessiter du temps. L'expiration prématurée du verrou peut permettre à une autre requête de modifier simultanément la même ressource.

Liste de vérification pour le dépannage rapide

• Vérifiez que l'erreur est liée à un verrouillage transactionnel et non à un verrouillage manuel créé par l'utilisateur.
• Vérifiez les journaux ownCloud, PHP, de la base de données et de Redis aux alentours du même horodatage.
• Vérifiez que Redis est accessible depuis l'environnement d'exécution ownCloud, et pas seulement depuis votre terminal.
• Réglé memcache.lockingsur \OC\Memcache\Redis.
• Gardez cette filelocking.enabledoption activée.
• Sur un cluster, configurez chaque nœud pour qu'il pointe vers la même instance Redis.
• Réessayez la synchronisation, le chargement ou le déplacement initial tout en surveillant les journaux.
• N’utilisez les analyses de réparation ou les modifications d’expiration des verrous que lorsque les preuves indiquent une altération des métadonnées ou des verrous obsolètes.

En résumé

La solution la plus fiable aux erreurs de délai d'attente lors du verrouillage de fichiers sur ownCloud ne consiste pas à supprimer les verrous ni à augmenter arbitrairement les délais. Commencez par identifier si l'erreur provient d'un verrouillage transactionnel, puis déplacez cette charge de travail vers Redis et assurez-vous que chaque nœud ownCloud accède à la même instance Redis. Testez à nouveau l'opération exacte qui a échoué et examinez la latence de la base de données ou du stockage si les verrous restent actifs trop longtemps.

Cette approche suit la documentation actuelle d'ownCloud : le verrouillage transactionnel des fichiers reste activé, Redis gère l'état de verrouillage partagé et les paramètres de délai d'expiration du verrouillage manuel des fichiers sont traités comme une fonctionnalité distincte plutôt que comme une solution universelle au problème de délai d'expiration du verrouillage.