Using occ with files: and groupfolders:

OwnCloud / Nextcloud ships a command‑line tool called occ (OwnCloud Console) that lets you manage the installation from the shell. Below is a practical guide for the most common file‑related tasks – listing, scanning, rebuilding and fixing issues such as bad locks or missing files – using the files: and groupfolders: commands.

---

1. Prerequisites

What you need	Why it matters
Root / sudo access	occ must be run as the web‑server user (usually www-data on Debian/Ubuntu or apache on CentOS).
Correct path to occ	Typically /var/www/nextcloud/occ (adjust to your installation folder).
Maintenance mode (optional)	Some operations are safer with the instance in maintenance mode, especially bulk scans or repairs.
Backup	Always have a recent database and data‑folder backup before running repair commands.

Example – switch to the web‑server user

sudo -u www-data php /var/www/nextcloud/occ ...

(Replace www-data with apache or the user you use.)

---

2. Listing Files

2.1 List a user’s files

sudo -u www-data php /var/www/nextcloud/occ files:list <username> [--path="/sub/folder"]

• <username> – the Nextcloud user you want to inspect.
• --path – optional; limits the list to a specific folder.
• Output is a simple table: File ID, Path, Size, Mimetype, ETag.

2.2 List all files in a Group Folder

sudo -u www-data php /var/www/nextcloud/occ groupfolders:list

Shows each group folder’s ID, name, permissions and the mount point (e.g. /groupfolders/12). To list the contents of a specific group folder:

sudo -u www-data php /var/www/nextcloud/occ files:list <admin_user> \
    --path="/groupfolders/<folder-id>"

(You need a user that has access to the folder – often the admin.)

---

3. Scanning / Re‑scanning Files

When files are added, moved or deleted directly on the storage (e.g. via FTP or a network share), Nextcloud’s file‑cache can become out of sync.

3.1 Scan a single user’s storage

sudo -u www-data php /var/www/nextcloud/occ files:scan <username>

• Scans the whole home folder of the user.
• Use --path="/sub/folder" to limit the scan.

3.2 Scan a specific Group Folder

Group folders are stored under the groupfolders mount point, so you can scan them like any other folder:

sudo -u www-data php /var/www/nextcloud/occ files:scan --path="/groupfolders/<folder-id>"

3.3 Scan all users (use with care)

sudo -u www-data php /var/www/nextcloud/occ files:scan --all

• This may take a long time on large installations; run it during a maintenance window.

---

4. Rebuilding the File Cache

If the file‑cache is severely corrupted (missing entries, duplicate entries, wrong sizes), a full rebuild is the safest option.

sudo -u www-data php /var/www/nextcloud/occ files:scan-app-data

• Re‑scans all data, including group folders, external storage, and app data.
• Equivalent to “rebuild the file‑cache from the filesystem”.

Tip: After a full rebuild, run a quick integrity check:

sudo -u www-data php /var/www/nextcloud/occ integrity:check-core

---

5. Fixing Bad Locks

A bad lock occurs when a file is left in a locked state (e.g. after an interrupted upload). Nextcloud stores locks in the database table ocfilelocks.

5.1 List current locks

sudo -u www-data php /var/www/nextcloud/occ files:cleanup

• This command removes expired locks (default TTL is 30 seconds).
• It also cleans up orphaned temporary files.

5.2 Manually delete a problematic lock

If a lock persists, you can delete it directly via the database (use with caution):

DELETE FROM oc_file_locks WHERE file_id = <FILE_ID>;

• Find the FILEID with files:list or by inspecting the ocfilecache table.
• Always backup the database before running manual SQL.

5.3 Force‑release all locks (last resort)

sudo -u www-data php /var/www/nextcloud/occ db:replace \
    "DELETE FROM oc_file_locks"

• This clears every lock – only do this when you are sure no uploads are in progress.

---

6. Dealing with Missing Files

Common causes: manual deletion from the data folder, failed sync, or a corrupted cache entry.

6.1 Verify the file exists on disk

find /var/www/nextcloud/data/<username>/files -type f -name "<filename>"

6.2 If the file is present on disk but not in Nextcloud

Run a targeted scan for the containing folder (see §3.2). This will re‑insert the missing cache entry.

6.3 If the file is absent on disk but still appears in Nextcloud

Remove the stale entry:

sudo -u www-data php /var/www/nextcloud/occ files:cleanup

or manually:

DELETE FROM oc_filecache WHERE fileid = <FILE_ID>;

After cleanup, run a scan so Nextcloud no longer shows the ghost file.

---

7. Typical Maintenance Workflow

1. Put the instance in maintenance mode (optional but recommended for bulk operations):

   sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on

1. Run the required commands (scan, rebuild, clean‑locks, etc.).
2. Check the logs for errors:

   tail -n 50 /var/www/nextcloud/data/nextcloud.log

1. Turn maintenance mode off:

   sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

1. Inform users that the service is back online.

---

8. Quick Reference Cheat‑Sheet

Goal	Command	Notes
List a user’s files	occ files:list <user>	Add --path="/folder" to narrow.
List group folders	occ groupfolders:list	Shows IDs for later use.
Scan a user	occ files:scan <user>	Use --path for a sub‑folder.
Scan a group folder	occ files:scan --path="/groupfolders/<id>"
Scan all users	occ files:scan --all	May take long.
Rebuild whole file cache	occ files:scan-app-data	Runs on every storage backend.
Remove expired locks	occ files:cleanup	Safe, runs automatically every 30 s.
Delete a specific lock	DELETE FROM ocfilelocks WHERE file_id = <id>;	DB‑level, backup first.
Clear all locks	occ db:replace "DELETE FROM ocfilelocks"	Use only when no uploads are active.
Put site in maintenance mode	occ maintenance:mode --on	Re‑enable with --off.
Verify data‑folder integrity	occ integrity:check-core	Shows missing or altered core files.

---

9. Final Tips

• Never edit the data folder directly unless you immediately run a scan.
• Always run a backup before using files:scan-app-data or any direct SQL.
• Check the version‑specific docs – some commands have changed between Nextcloud 24‑27.
• Log monitoring: a sudden rise in “File not found” or “Bad lock” entries in nextcloud.log often indicates a systemic issue that may need a full cache rebuild.

With these occ commands you can reliably list, scan, rebuild and repair the file system inside Nextcloud, fixing the usual culprits such as bad locks, missing files, or stale cache entries. If problems persist after the steps above, consider checking external‑storage mounts, file‑system permissions, and the web‑server error log for deeper clues.