Résoudre l'erreur « Base de données » de l'interface Web de Nextcloud après une mise à jour : Guide pratique de récupération

Un message d'erreur tel que « Exception : Erreur de base de données » s'affichant dans l'interface web de Nextcloud immédiatement après une mise à jour signifie généralement que l'application web parvient à accéder à la base de données, mais qu'une requête, une migration, une attente de schéma, une connexion ou une opération de base de données spécifique à l'application échoue. Ne commencez pas par supprimer des tables, réinstaller Nextcloud ou restaurer un ancien répertoire de code par-dessus le nouveau. La procédure la plus sûre consiste à identifier la requête SQL ou la migration défaillante, à terminer la procédure de mise à jour prise en charge, à réparer uniquement ce que Nextcloud peut réparer, puis à vérifier le service et le schéma de la base de données avant de rétablir l'accès.

Cette documentation de référence suit la documentation d'administration de Nextcloud 35 disponible en octobre 2026. Les commandes ci-dessous supposent une installation standard de type Debian/Ubuntu avec /var/www/nextcloudl'utilisateur du serveur web www-data. Adaptez le chemin d'accès, l'exécutable PHP, la commande du conteneur ou l'utilisateur HTTP à votre déploiement.

Diagnostic rapide : ce que l’erreur indique généralement

1. Préservez l'état actuel avant d'apporter des modifications à la base de données.

Si vous disposez encore de votre sauvegarde antérieure à la mise à jour, conservez-la intacte. Nextcloud recommande explicitement une sauvegarde avant chaque mise à jour ; la sauvegarde intégrée à son outil de mise à jour couvre le code source, mais pas la base de données ni le répertoire de données . Si vous ne possédez pas de sauvegarde récente de votre base de données, créez-en une à l'aide de l'outil de sauvegarde standard de votre plateforme avant toute modification ou restauration manuelle de requêtes SQL.

Évitez de revenir à une version antérieure comme solution de fortune. Nextcloud indique que cette opération n'est pas prise en charge et peut corrompre les données. Si une restauration s'avère nécessaire, la méthode recommandée consiste à réinstaller la version précédente, puis à restaurer une sauvegarde correspondante. Il est déconseillé de copier d'anciens fichiers système sur une base de données dont la migration a déjà commencé. Consultez la documentation relative à l'outil de mise à jour intégré de Nextcloud .

2. Lisez l'exception de base de données exacte dans le journal Nextcloud.

Avec la journalisation par fichier, le journal par défaut se trouve nextcloud.logdans le répertoire de données configuré. Le guide de dépannage de Nextcloud recommande de consulter ce journal et, le cas échéant, les journaux du serveur web et de PHP. Si la page d'erreur affiche un ID de requête, recherchez cet ID pour identifier la transaction correspondante.

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

Ne réduisez pas le journal à la simple mention « Erreur de base de données ». Notez le code SQLSTATE, la classe d'exception, la table ou la colonne défaillante, ainsi que l'application ou le composant principal mentionné dans la trace de la pile. Par exemple, l'erreur « table introuvable » est très différente des erreurs « trop de connexions » ou « le serveur MySQL a été déconnecté ». Nextcloud répertorie plusieurs erreurs courantes de type SQLSTATE dans sa documentation de dépannage générale .

3. Vérifiez si la mise à jour est bien terminée.

Le programme de mise à jour intégré remplace d'abord le code Nextcloud. Les migrations de la base de données et de l'application constituent une étape distincte. En mode ligne de commande, le programme de mise à jour peut s'exécuter occ upgradeautomatiquement ; sinon, la migration doit être effectuée ultérieurement. Cette distinction explique de nombreux cas où la mise à jour semble terminée, mais où l'interface Web classique renvoie une exception de base de données.

cd /var/www/nextcloud
sudo -E -u www-data php occ status

Si vous devez protéger l'instance pendant le dépannage, activez le mode maintenance. Nextcloud décrit ce mode comme étant destiné aux mises à niveau, car il empêche les nouvelles connexions et verrouille les sessions actives.

sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ status

4. Terminez les migrations de bases de données et d'applications prises en charge avec la mise à niveau occ.

Si le code a été mis à jour mais que les migrations n'ont pas abouti, exécutez la commande de mise à niveau en tant qu'utilisateur HTTP :

cd /var/www/nextcloud
sudo -E -u www-data php occ upgrade

Surveillez la sortie jusqu'à ce que la commande indique une réussite ou s'arrête en cas d'erreur spécifique. Si elle échoue, corrigez le problème avant de la relancer. Les causes fréquentes d'échec incluent une application incompatible, une version de PHP/base de données non prise en charge, un service de base de données indisponible ou des autorisations empêchant les mises à jour nécessaires. N'actualisez pas l'interface web de manière répétée pendant l'échec de la migration.

La documentation de mise à jour de Nextcloud recommande également de ne pas sauter de versions majeures. Lors du passage d'une version majeure à une autre, effectuez la mise à jour progressivement.

5. Exécutez la procédure de réparation de Nextcloud une fois le problème de migration résolu.

maintenance:repairCette commande exécute les étapes de réparation de Nextcloud et s'exécute également automatiquement lors des mises à jour. Il est judicieux de l'exécuter manuellement une fois que vous avez résolu le problème qui a interrompu la mise à jour.

sudo -E -u www-data php occ maintenance:repair

Cette méthode est plus sûre que la création de requêtes SQL, car les étapes de réparation sont fournies par le noyau et les applications Nextcloud. Il ne s'agit pas d'une solution miracle occ upgradeet elle ne permettra pas de réparer un serveur de base de données défaillant ou une version de base de données non prise en charge. La commande est documentée dans la section « Commandes système et de maintenance de Nextcloud » .

6. Vérifiez le service de base de données, les paramètres de connexion et la version prise en charge.

Si le journal indique un problème de connectivité plutôt que de schéma, vérifiez que le service de base de données est en cours d'exécution et accessible depuis l'environnement PHP de Nextcloud. Sur un serveur MariaDB classique, une vérification utile consiste à :

sudo systemctl status mariadb

Vérifiez ensuite les paramètres de la base de donnéesconfig/config.php : type, hôte, nom, utilisateur et paramètres de socket ou de port. Une erreur de socket Unix peut se manifester par « Fichier ou répertoire introuvable », tandis qu’une base de données distante peut échouer en raison de problèmes de routage, de DNS, de TLS, de règles de pare-feu, d’identifiants ou du serveur lui-même.

La compatibilité des versions est importante après une mise à jour majeure de Nextcloud. Pour Nextcloud 35, les notes de version officielles indiquent que MariaDB 10.6 et MySQL 8.0 ne sont plus pris en charge ; les versions minimales requises sont MariaDB 10.11 LTS et MySQL 8.4 LTS. Vérifiez la configuration requise pour votre version majeure de Nextcloud avant de mettre à niveau la base de données. Consultez la page Mise à niveau vers Nextcloud 35 .

7. Examinez les écarts de schéma et ajoutez uniquement les structures manquantes documentées.

Nextcloud 35 ajoute une db:schema:checkfonctionnalité qui compare le schéma en direct avec le schéma attendu par le noyau installé et les migrations d'applications. Cette fonctionnalité est en lecture seule : elle signale les différences sans modifier la base de données.

sudo -E -u www-data php occ db:schema:check
sudo -E -u www-data php occ db:schema:check -v

Si l'aperçu de l'administrateur ou la sortie de la commande signale des colonnes facultatives, des index ou des clés primaires manquants, utilisez les commandes de maintenance documentées :

sudo -E -u www-data php occ db:add-missing-columns
sudo -E -u www-data php occ db:add-missing-indices
sudo -E -u www-data php occ db:add-missing-primary-keys

Chacune --dry-runde ces commandes permet de prévisualiser le code SQL. Elles ne doivent pas être utilisées en remplacement d'une migration de base ayant échoué. Si db:schema:checkdes objets inattendus ou des différences de propriétés de colonnes sont signalés, examinez attentivement le rapport avant toute modification ; Nextcloud indique que certaines valeurs par défaut de la base de données ne correspondent pas au modèle de schéma attendu. La documentation de référence est « Commandes Nextcloud DAV et de base de données » .

8. Isolez les défaillances des applications tierces avant de rouvrir l'interface Web.

Si la trace de pile mentionne une application non fournie avec Nextcloud, sa migration risque d'être incompatible avec la nouvelle version du serveur. Le guide de dépannage de Nextcloud recommande de désactiver les applications tierces/non fournies avec Nextcloud pour les mises à jour et le dépannage. Utilisez les commandes disponibles dans votre version installée pour désactiver l'application suspecte depuis la ligne de commande, puis relancez occ upgradela commande et ne réactivez l'application qu'après avoir confirmé la compatibilité de la version.

Cette branche est particulièrement importante lorsque les tables principales semblent saines, mais que l'exception fait référence à un espace de noms fournisseur ou à une table appartenant à une application. Supprimer manuellement les tables de cette application est risqué, car vous pourriez détruire des données dont l'application a encore besoin.

9. Quittez le mode maintenance et vérifiez plus que la page de connexion.

Une fois occ upgradeles opérations terminées, si les vérifications de réparation/schéma ne signalent plus de problème bloquant et que le service de base de données est stable, désactivez le mode maintenance :

sudo -E -u www-data php occ maintenance:mode --off

Vérifiez ensuite l'instance étape par étape : chargez la page de connexion, connectez-vous, ouvrez le fichier « Fichiers », parcourez quelques dossiers, effectuez un test de téléchargement/téléversement de fichier, vérifiez les paramètres d'administration pour détecter d'éventuels avertissements et consultez les dernières nextcloud.logentrées. Assurez-vous également que les tâches planifiées (cron) et les tâches en arrière-plan s'exécutent correctement. Le simple fait qu'une page d'accueil soit restaurée ne garantit pas le bon fonctionnement des migrations d'applications, des opérations sur les fichiers et des tâches en arrière-plan.

Liste de contrôle de récupération

• Conservez votre sauvegarde antérieure à la mise à jour et évitez une rétrogradation non prise en charge.
• Veuillez lire l'exception complète de la base de données dans nextcloud.log, y compris SQLSTATE et le composant nommé dans la trace.
• Vérifiez occ statuset placez l'instance en mode maintenance pendant la réparation.
• Exécutez cette commande occ upgradepour terminer les migrations principales et applicatives prises en charge.
• Corrigez le premier obstacle concret au lieu de modifier les tables de la base de données à l'aveuglette.
• Exécutez- maintenance:repairle une fois la panne sous-jacente corrigée.
• Vérifiez l'état du service de base de données, les paramètres de connexion et la compatibilité des versions.
• À utiliser db:schema:checksur Nextcloud 35 et avec les db:add-missing-*commandes documentées, le cas échéant.
• Désactivez l'application tierce défaillante si la trace d'erreur la désigne clairement, puis réessayez la mise à niveau.
• Désactivez le mode maintenance uniquement après la réussite des vérifications en ligne de commande, puis testez les fichiers, les transferts, les avertissements d'administration, les journaux et les tâches en arrière-plan.

Quand restaurer plutôt que réparer

Restaurez les données à partir d'une sauvegarde interne fiable et cohérente si la base de données est endommagée, si des migrations ont partiellement modifié des données de manière irréversible, ou si des tables/données essentielles ont été supprimées en dehors de Nextcloud. La base de données, la configuration, le répertoire de données et la version du code doivent appartenir à un point de récupération compatible. Si vous bénéficiez d'un support Nextcloud payant ou s'il s'agit d'un déploiement critique, évitez toute modification SQL destructive et fournissez à votre service d'assistance l'intégralité du journal, les versions exactes de Nextcloud source et cible, le type et la version de la base de données, la version de PHP et le résultat de la occcommande appropriée.

Le principe de base est simple : une erreur de base de données après une mise à jour ne justifie pas de tenter des interprétations SQL hasardeuses. Laissez le journal identifier l’erreur, terminez occ upgradeles migrations prévues, utilisez les outils de réparation et de schéma de Nextcloud, puis validez la plateforme de base de données avant de rouvrir l’instance.