How to fix locked files in Nextcloud

Nextcloud file locks protect files while people edit documents, sync clients upload changes, or apps update file metadata. A stale lock becomes visible when the affected file is no longer being changed but the user still cannot rename, delete, overwrite, or sync it.

Current Nextcloud releases include an occ file-lock command for checking and unlocking a known file ID. Use that command before considering lower-level cache or database work, because removing lock records from the wrong backend can clear an active write or fail to touch the lock that is actually blocking the file.

The path in occ file commands is the user's Nextcloud file path, such as /ada/report.docx, not the server filesystem path under the data directory. Confirm that the affected editor, upload, or sync client has stopped before unlocking; if the lock returns immediately, treat it as an active writer or a transactional locking backend problem rather than repeating the unlock command.

1. Stop the active editor, upload, or sync client for the affected file.

   Do not unlock a file that is still uploading, open in an editor, or syncing from another device. Removing an active lock can let two writers change the same file at the same time.

2. Find the Nextcloud file ID for the affected user-visible path from the Nextcloud web root.

   $ sudo -E -u www-data php occ info:file /ada/report.docx
   report.docx
     fileid: 1248
     mimetype: application/vnd.openxmlformats-officedocument.wordprocessingml.document
     modified: June 28, 2026, 11:02:48 PM UTC
     size: 42 KB
     etag: 5a31b7b0fbc169c9f0d5d1d9a84136d0
     permissions: full permissions
   
   The following users have access to the file
   
   ada:
     /ada/report.docx: full permissions
       home storage

   Use the user ID and file path shown in the failed operation or log entry. On packaged installs with a different web user, web root, or wrapper, keep the same occ command shape and replace www-data or php occ with the local values.

3. Check whether Nextcloud reports an app-level lock on that file ID.

   $ sudo -E -u www-data php occ files:lock --status 1248 ada
   File #1248 is locked by ada
    - Locked at: 2026-06-28T23:15:22+00:00
    - Expiry in seconds: 3600

   If the command reports File #1248 is not locked while uploads or WebDAV requests still fail with LockedException or FileLocked messages, inspect the Nextcloud log and the configured locking cache instead of clearing database rows manually.
   Related: How to view Nextcloud logs
   Related: How to configure Redis caching for Nextcloud

4. Unlock the stale file ID for the affected user.

   $ sudo -E -u www-data php occ files:lock --unlock 1248 ada
   unlocking File #1248

   Use the file ID returned by info:file. Unlocking a neighboring ID can affect another user's file when shared folders or group folders expose similar names.

5. Recheck the lock status for the same file ID.

   $ sudo -E -u www-data php occ files:lock --status 1248 ada
   File #1248 is not locked

6. Retry the original file operation through the same path that failed.

   $ sudo -E -u www-data php occ files:move /ada/report.docx /ada/report-fixed.docx

   For a GUI or desktop-client incident, repeat the original rename, delete, upload, or sync action there instead of substituting an occ move. The same operation that failed because of the lock should now succeed.

7. Confirm that Nextcloud sees the file at the expected final path.

   $ sudo -E -u www-data php occ info:file /ada/report-fixed.docx
   report-fixed.docx
     fileid: 1248
     mimetype: application/vnd.openxmlformats-officedocument.wordprocessingml.document
     modified: June 28, 2026, 11:02:48 PM UTC
     size: 42 KB
     etag: 5a31b7b0fbc169c9f0d5d1d9a84136d0
     permissions: full permissions
   
   The following users have access to the file
   
   ada:
     /ada/report-fixed.docx: full permissions
       home storage

   If the same file locks again immediately, leave the file locked and investigate the writer that is recreating the lock, such as an Office session, sync client, WebDAV mount, external storage backend, or Redis locking cache.