Rédigé par Rédaction CyberSDF / 19 September 2026

occ files:scan : rendre visibles des fichiers copiés dans le dossier data

Un dossier copié avec cp ou rsync dans /var/www/nextcloud/data/alice/files n’apparaît pas dans l’interface web : Nextcloud ne connaît que les fichiers inscrits dans son cache, et une copie faite hors de l’interface ne l’alimente pas. La commande qui corrige la situation est sudo -E -u www-data php occ files:scan alice. Elle relit l’arborescence réelle et inscrit les nouveaux fichiers dans le cache, sans lire leur contenu. Dans Nextcloud 35, le contrôle automatique du dossier data est désactivé par défaut, la valeur par défaut de filesystem_check_changes étant 0.

Sous Debian et Ubuntu, l’installation type vit dans /var/www/nextcloud avec le compte www-data, comme sur une instance de stockage personnel. Sur Arch, le paquet nextcloud utilise le compte nextcloud et un lanceur /usr/bin/occ qui change d’utilisateur lui-même ; sur une installation snap, la commande devient sudo nextcloud.occ files:scan --all.

filesystem_check_changes vaut 0 : une copie dans data/ ne déclenche aucun contrôle

Le fichier config.sample.php de Nextcloud 35 déclare ’filesystem_check_changes’ => 0, et le commentaire du paramètre donne les deux valeurs possibles : 0 ne vérifie jamais le système de fichiers, 1 vérifie chaque fichier ou dossier au plus une fois par requête. La portée est limitée au dossier data/ local et aux montages NFS placés dedans ; le stockage externe n’est pas concerné par ce réglage. Un fichier posé à la main dans data/alice/files reste donc absent de l’interface aussi longtemps qu’aucun scan ne l’inscrit.

Une tâche de fond rattrape les oublis : elle passe toutes les 10 minutes et scanne les fichiers dont la taille est inconnue dans le cache, soit une taille négative dans la table filecache, pour 500 utilisateurs au maximum par passage. Elle est active par défaut, le paramètre files_no_background_scan de Nextcloud 35 valant false. Ce délai suffit pour une copie oubliée, pas pour livrer un dossier dans la minute.

Aligner le propriétaire, puis lancer occ files:scan

La commande doit tourner sous le compte qui possède config/config.php, qui doit aussi pouvoir lire les fichiers copiés. La suite part d’un dossier /var/www/nextcloud/data/alice/files/Rapports copié par root.

1. Relever le compte propriétaire de la configuration.

   stat -c '%U:%G %a %n' /var/www/nextcloud/config/config.php

   Ce que vous devez voir : une ligne du type www-data:www-data 640 /var/www/nextcloud/config/config.php. Un root en première colonne annonce l’arrêt de toutes les commandes occ lancées en www-data, sur le message Console has to be executed with the user that owns the file config/config.php.

2. Rendre la copie accessible au serveur web.

   sudo chown -R www-data:www-data /var/www/nextcloud/data/alice/files/Rapports

   Ce que vous devez voir : rien. chown n’affiche que les erreurs ; un ls -ld sur le dossier montre ensuite www-data en troisième colonne, avec des modes qui se lisent comme dans les permissions et utilisateurs sous Linux.

3. Scanner le compte concerné.

   cd /var/www/nextcloud
   sudo -E -u www-data php occ files:scan alice

   Ce que vous devez voir : la ligne Starting scan for user 1 out of 1 (alice), puis le tableau des compteurs.

   +---------+-------+-----+---------+---------+--------+--------------+
   | Folders | Files | New | Updated | Removed | Errors | Elapsed time |
   +---------+-------+-----+---------+---------+--------+--------------+
   | 24      | 318   | 312 | 0       | 0       | 0      | 00:00:06     |
   +---------+-------+-----+---------+---------+--------+--------------+

   La colonne New compte les fichiers ajoutés au cache, Files le total parcouru, et Errors doit rester à 0. Les chiffres exacts dépendent de l’arborescence.

4. Nommer chaque fichier traité, puis vérifier dans l’interface.

   sudo -E -u www-data php occ files:scan --path="/alice/files/Rapports" -v

   Ce que vous devez voir : une ligne commençant par File suivie du chemin complet de chaque fichier, puis le même tableau limité au dossier visé. La page Fichiers affiche le dossier après rechargement, avec la taille recalculée par le scan.

Le chemin de –path est un chemin Nextcloud, pas un chemin disque

Le manuel Nextcloud 35 l’écrit sans détour : le chemin passé à –path doit contenir l’identifiant de l’utilisateur et le dossier files/, et –path, –all et un identifiant de compte s’excluent l’un l’autre. La forme correcte est --path="/alice/files/Rapports", l’option courte équivalente étant -p. Un chemin pris dans le système de fichiers ne peut pas fonctionner : dans la branche stable35, le code retient le deuxième segment du chemin comme nom de compte. Pour --path="/var/www/nextcloud/data/alice/files", ce segment vaut var et la réponse est Unknown user 1 var.

Ce que la commande répond quand elle s’arrête

Les six messages ci-dessous sont repris du code de la branche stable35. Trois d’entre eux sont suivis d’une ligne de détail, et le compteur Errors du tableau final passe à 1 à chaque fois.

Please specify the user id to scan, --all to scan for all users or --path=...
Unknown user 1 var
Home storage for user alice not writable or 'files' subdirectory missing
  User folder /var/www/nextcloud/data/alice/files is not writable, folders is owned by root and has mode 40755
Make sure you're running the scan command only as the user the web server runs as
Path not found: /alice/files/Photos
Another process is already scanning 'alice'
Console has to be executed with the user that owns the file config/config.php

Sur un stockage SMB, un dossier sans droits arrête tout le scan

Le rapport 54446 du dépôt Nextcloud, ouvert le 16 août 2025, décrit un scan qui s’interrompt au premier sous-dossier illisible d’un montage externe SMB. Le cas a été déposé depuis un Nextcloud Server 31 sous Debian ou Ubuntu, avec Nginx et PHP 8.4. La commande affiche Error during scan: Couldn't open SMB directory smb://…: Path does not exist et s’arrête là : les dossiers suivants restent hors de l’index. Le journal porte alors la ligne User <username> still has unscanned files after running background scan, background scan might be stopped prematurely.

La suite coûte plus cher que le message : le client de bureau compare son état local à l’index, conclut que les fichiers absents ont été supprimés, et les renvoie. Le rapport chiffre la relance à plus de 500 Go de transferts inutiles avant correction des droits côté SMB. Deux contournements existent : –home-only laisse les montages externes de côté, et un scan –path limité aux dossiers lisibles indexe le reste. Le rapport est resté ouvert, étiqueté Needs triage, sans version ciblée.

Dossiers de groupe, stockage externe, appdata : trois commandes de scan distinctes

Un dossier de groupe n’appartient à aucun compte personnel. L’application Group folders fournit ses propres commandes : occ groupfolders:list affiche les identifiants, et occ groupfolders:scan 2 relance l’indexation d’un de ces espaces. Un montage externe dispose de la sienne, occ files_external:scan 1, décrite dans la section Files external du manuel Nextcloud 35, pour les backends qui ne signalent pas leurs changements.

Les aperçus, les avatars et les feuilles de style en cache vivent dans appdata ; ils se rafraîchissent avec occ files:scan-app-data, une commande séparée sans tâche de fond équivalente. Après restauration d’une sauvegarde qui contient appdata, c’est elle qui remet les vignettes d’aplomb, pas files:scan. Le reste de la rubrique Logiciels couvre les services voisins.