"I copied the files straight into the folder via SCP, but nothing shows up in Nextcloud." The files are there, an ls on the server proves it. Nextcloud just doesn't know about them.
Why the files are invisible
Nextcloud doesn't read the whole file system on every page load. Instead it keeps a file cache in the database (the filecache table, e.g. oc_filecache depending on the prefix) with path, size, modification time, ETag and permissions for each file. The web UI, sync clients, shares and search all work from these entries.
When a file arrives through the web UI, WebDAV or a client, Nextcloud creates the entry itself. When it is copied directly into the data directory – with SCP, rsync, cp or a mounted drive – the entry is missing. As far as Nextcloud is concerned, the file doesn't exist.
The fix: occ files:scan
The files:scan command reconciles the file system with the database. Run it as the web server user from the Nextcloud directory; on Debian and Ubuntu that is usually www-data:
cd /var/www/nextcloud
sudo -u www-data php occ files:scan --path="user/files/folder"The path starts with the user ID, followed by files and the folder inside the user's directory. Scanning only that subtree is much faster than scanning a whole user.
Other variants:
# all files of one user
sudo -u www-data php occ files:scan user
# all users (can take a long time on large instances)
sudo -u www-data php occ files:scan --allIf Nextcloud runs in the official Docker image, run the command inside the container:
docker exec -u www-data nextcloud php occ files:scan --path="user/files/folder"The container name may differ in your setup.
Common pitfalls
Wrong user. occ has to run as the user who owns config/config.php. Started as root, it stops with a message saying so. Always use sudo -u www-data (or whatever your web server user is).
Wrong ownership. Copied files often belong to whoever copied them, so the web server can't read or modify them. Fix this before scanning:
chown -R www-data:www-data /var/www/nextcloud/data/user/files/folderThe data directory isn't always /var/www/nextcloud/data. The real path is set as datadirectory in config/config.php.
Encryption. With server-side encryption enabled, you can't simply drop unencrypted files into the data directory. The only route then is WebDAV or a client.
Managed hosting. Managed Nextcloud instances usually offer no shell access and therefore no occ. There, uploading through the official interfaces is the only way anyway.
Better next time: upload through Nextcloud
The cleanest way is not to bypass the server at all. Then file system and database stay in sync automatically, and versions, shares and notifications work as expected.
- Desktop client: put the files into the synced folder.
- WebDAV: for example with a file manager or
rcloneagainsthttps://cloud.example.com/remote.php/dav/files/USER/. - Large data sets: WebDAV again, with a tool that handles retries and parallel transfers.
There is an option filesystem_check_changes in config.php that makes Nextcloud look for changes on access. It costs performance, though, and is not a good permanent answer to regular direct copies.
How to check
- Are the files in the right path below
datadirectory? - Are they owned by the web server user?
- Was
occ files:scanrun as the web server user with the right--path? - Did you read the scan output (folders, files, errors)?
- Did you reload the web UI to confirm everything is visible?
- Are future uploads planned via WebDAV or the client?
If you deal with Nextcloud issues regularly, the blog also has an article on common SAML and OIDC errors. The rule from this case applies everywhere, though: Nextcloud shows what is in its database – and nothing more.