Fix Nextcloud “Transactional File Locking Is Not Configured”

If Nextcloud shows a warning that transactional file locking is not configured or is disabled, file operations may be less protected against simultaneous writes and interrupted transfers. The usual fix is to configure a supported key-value store such as Redis or Valkey for locking. First identify how Nextcloud is installed, then configure the cache service and Nextcloud together; installing Redis alone does not clear the warning.

Nextcloud’s current Administration Manual says transactional locking uses the database by default. The database backend can work, but it adds database load. Redis or Valkey can provide a dedicated locking backend. The exact warning text varies by Nextcloud release: current documentation lists “Transactional file locking is disabled, this might lead to issues with race conditions.” A separate memory-cache warning is not the same issue. See the official transactional file locking guide and Admin page warning reference.

Before you change the server

These steps assume you administer the Nextcloud host. Commands below use Debian or Ubuntu with a conventional package installation; package names, service names, PHP versions, and configuration paths vary on other Linux distributions. If you run Nextcloud AIO, Docker, Snap, TrueNAS, or a hosting-provider image, follow that deployment’s instructions for installing and restarting services. Installing PHP packages on the host may not change the PHP environment inside a container or appliance.

• Find the Nextcloud web root and its active config/config.php.
• Make a protected backup of that file before editing it. It can contain database credentials and other secrets.
• Confirm whether Nextcloud uses one web server or several. A multi-node setup needs one shared Redis/Valkey server or cluster reachable by every Nextcloud node.
• Plan a short maintenance window if your users depend on uninterrupted file uploads.

Step 1: Confirm the warning and installation type

Sign in as an administrator and open Administration settings, then review the overview or security and setup warnings. Record the exact message. If the page only says that no memory cache is configured, that is a different check; configure a local cache such as APCu as appropriate, but do not assume it will provide transactional locking. Nextcloud documents that cache settings must be explicitly enabled in config.php.

On a traditional Linux install, use the shell to identify the deployment path and inspect the configuration file without printing secrets into a shared terminal log. For example, from the server:

cd /var/www/nextcloud
ls -l config/config.php

Replace /var/www/nextcloud with your actual path. For containers, identify the container and its mounted configuration instead of editing a host-side file that the running instance does not use.

Step 2: Install and start a key-value store

For Debian or Ubuntu, the traditional Redis backend typically uses the Redis service and the PHP Redis extension. Install packages that match the PHP version used by the web server:

sudo apt update
sudo apt install redis-server php-redis
sudo systemctl enable --now redis-server
sudo systemctl status redis-server

The status output should report that the service is active. Confirm that the PHP runtime serving Nextcloud can load the Redis extension. On a standard installation, php -m | grep -i redis is a quick CLI check, but CLI PHP and web PHP can use different versions or configuration files. If the module is absent in the web runtime, install or enable the matching package and restart PHP-FPM or the web server.

Nextcloud 34.0.2 and later also provide a bundled KeyValueCache backend for Redis-compatible stores. It does not require the PHP Redis extension. This can be useful when a hosting environment cannot install PHP modules, but it still requires a running Redis or Valkey service. The current Nextcloud memory caching guide documents both approaches. Choose one backend configuration below rather than adding both.

Step 3: Configure locking in Nextcloud

Edit the active config/config.php and add the selected entries inside the existing $CONFIG array. Preserve the PHP syntax and commas. Do not create a second configuration array or duplicate keys. Keep any existing cache settings unless you understand why they need to change.

Option A: Redis with the PHP Redis extension

Use this option when the web PHP runtime has the supported phpredis extension installed. A local Redis server listening on port 6379 can use a configuration like this:

'memcache.locking' => '\OC\Memcache\Redis',
'redis' => [
    'host' => '127.0.0.1',
    'port' => 6379,
    'timeout' => 0.0,
],

If Redis requires authentication, configure the correct password in config.php and secure the file’s permissions. Do not expose Redis publicly. Keep it bound to localhost or a protected private network, and use a Unix socket where appropriate.

Option B: KeyValueCache with Redis or Valkey

Use this option when your Nextcloud version supports the bundled provider and you prefer not to install a PHP Redis extension. For a local service listening on port 6379, the minimal example is:

'memcache.locking' => '\OC\Memcache\KeyValueCache',
'memcache.kvstore' => [
    'server' => [
        'host' => '127.0.0.1',
        'port' => 6379,
    ],
],

Add the documented authentication, TLS, socket, Sentinel, or cluster settings if your service uses them. Do not copy credentials from an example. For detailed parameters and supported topologies, use the official cache configuration reference.

Step 4: Check connectivity and multi-server settings

Nextcloud must be able to reach the configured cache server using the same host, port, socket, and credentials as the service. A common mistake is to set localhost in each Nextcloud web node while Redis runs on only one separate host. In a multi-server deployment, configure all web nodes to use the same Redis server or cluster. Restrict network access to the Nextcloud nodes and protect Redis with appropriate authentication and firewall rules.

For a Unix socket, confirm that the PHP/web-server account can read and write the socket. Permission or group changes differ by operating system, so follow the Redis/Valkey and distribution documentation rather than applying broad permissions such as world-writable access. A connection refusal, authentication error, or socket permission error can prevent Nextcloud from using the locking provider even when the configuration key is present.

Step 5: Restart the right services

After saving the configuration, restart the Redis service if its settings changed, then restart the PHP runtime that serves Nextcloud. For example, an Apache installation may require an Apache restart, while a PHP-FPM installation requires restarting the matching PHP-FPM service. Service names include PHP version numbers on some distributions. With containers, recreate or restart the relevant service through the deployment’s supported method. Avoid restarting unrelated services blindly on a production server.

If Nextcloud returns a configuration or syntax error, restore the backup and check for a missing comma, mismatched quote, duplicate key, or edit to the wrong config.php. PHP’s array settings must remain inside the existing configuration structure.

Step 6: Verify configuration and test file operations

Refresh the administrator overview and check whether the transactional file-locking warning has disappeared. If you configured a local cache and still see a memory-cache warning, check that separately; Nextcloud recommends APCu for local caching on many single-server deployments while Redis handles locking and distributed caching. Do not add Redis as the local cache by default, especially in a multi-server configuration.

You can also inspect the effective locking setting with Nextcloud’s command-line tool. Run occ from the Nextcloud directory as the web-server account; on Debian/Ubuntu that account is commonly www-data:

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

The value should match the backend you chose, such as \OC\Memcache\Redis or \OC\Memcache\KeyValueCache. If the command cannot find the setting, verify the path, execution user, and active configuration file. The official OCC guide explains how to run administrative commands.

Finally, upload a small test file, rename it, download it, and confirm that a desktop or mobile client can sync a change. These checks do not simulate every concurrent workload, but they confirm that ordinary file operations still work after the change. For a busy or clustered server, monitor the Nextcloud log and Redis/Valkey availability during normal use. If the warning remains, verify that the web PHP runtime has the extension when using Option A, the cache host is reachable, credentials and socket permissions are correct, and all nodes share the same backend.

What transactional file locking does—and does not do

Transactional locking helps prevent file corruption when operations overlap, handles interrupted transactions, and coordinates changes involving shared files and external storage. It does not reserve a document so only one person can edit it, display who else is editing, or merge simultaneous edits. Treat the warning as a server configuration issue, then test normal uploads and syncing after the backend is configured. For collaborative editing behavior, use an application designed for co-authoring rather than relying on file locks.