Mongoose : dépannage

Procédure de diagnostic

node --version
npm ls mongoose
sudo systemctl status mongod
mongosh "mongodb://127.0.0.1:27017" --eval 'db.runCommand({ ping: 1 })'
sudo journalctl -u mongod -n 30 --no-pager
sudo journalctl -u monapi -n 50 --no-pager

Activer temporairement l’affichage des requêtes :

mongoose.set('debug', true);

Contrôler les données directement dans mongosh (voir MongoDB : console) pour distinguer un problème de requête d’un problème de données.

Erreurs de connexion

Message	Cause et solution
`MongooseServerSelectionError: connect ECONNREFUSED`	MongoDB arrêté, mauvaise adresse ou port : `sudo systemctl status mongod`, `sudo ss -tlnp \| grep 27017`
`Server selection timed out after 5000 ms`	Serveur injoignable ou pare-feu ; avec un replica set, nom d’hôte non résolu
`MongoServerError: Authentication failed`	Utilisateur, mot de passe ou `authSource` incorrects
`MongoServerError: command find requires authentication`	Authentification activée côté serveur, URI sans identifiants
`MongoServerError: not authorized on boutique to execute command`	Rôle insuffisant : voir MongoDB : utilisateurs et droits
`MongoParseError` / `URI malformed`	Caractères spéciaux du mot de passe non encodés
`Operation \`clients.find()` buffering timed out after 10000ms`	Requête lancée sans connexion établie : attendre `await mongoose.connect()`
`MongooseError: Can't call openUri() on an active connection with different connection strings`	`connect()` appelé deux fois : une seule connexion par processus
`MongoNotConnectedError`	Connexion fermée ou perdue

Erreurs de données

Message	Cause et solution
`ValidationError: … is required`	Champ obligatoire absent
`CastError: Cast to ObjectId failed for value "x" at path "_id"`	Identifiant invalide : `mongoose.isValidObjectId(id)`
`CastError: Cast to Number failed`	Type incorrect (chaîne non numérique)
`MongoServerError: E11000 duplicate key error … dup key: { email: … }`	Doublon sur un index unique
`StrictModeError`	Champ non déclaré dans un filtre avec `strictQuery` strict
`VersionError: No matching document found for id`	Document modifié ailleurs entre lecture et enregistrement (tableau)
`DocumentNotFoundError`	`save()` sur un document supprimé
`ParallelSaveError`	Deux `save()` simultanés du même document : attendre le premier
`OverwriteModelError`	Modèle compilé deux fois (rechargement à chaud)
`MissingSchemaError`	Modèle référencé par `populate` non importé
`MongoServerError: Transaction numbers are only allowed on a replica set`	Transactions sans replica set

Résultats inattendus

Symptôme	Piste
`find` renvoie `[]`	Collection et base : nom pluriel automatique (`clients`), `dbName`, filtre (types : chaîne ou nombre)
Un champ n’est pas enregistré	Absent du schéma (`strict`)
Une mise à jour ne change rien	Filtre qui ne correspond à rien (`matchedCount` à 0), champ absent du schéma
`populate` laisse `null`	Document référencé supprimé, `ref` erroné
Le champ de mot de passe n’est pas lu	`select: false` : `.select('+motDePasse')`
`lean()` : plus de méthodes	Comportement normal
Date décalée	Les dates sont en UTC : formater à l’affichage
Nombre décimal imprécis	Utiliser des centimes entiers ou `Decimal128`

Vérifier le résultat d’une mise à jour :

const r = await Client.updateOne({ email }, { $set: { actif: false } });
console.log(r.matchedCount, r.modifiedCount);

matchedCount à 0 : le filtre ne correspond à rien ; modifiedCount à 0 : la valeur était déjà celle demandée.

Performances

Symptôme	Piste
Requête lente	`explain('executionStats')`, index manquant (voir Performances et production)
Mémoire élevée	`lean()`, `select`, pagination, curseur
Trop de connexions	Réduire `maxPoolSize` ou le nombre d’instances
Démarrage lent	`autoIndex: false` en production

Tests

Pour les tests automatiques, utiliser une base dédiée :

import { test, before, after } from 'node:test';
import assert from 'node:assert/strict';
import mongoose from 'mongoose';
import { Client } from '../src/models/client.js';

before(async () => {
  await mongoose.connect(process.env.MONGODB_URI_TEST);
  await Client.deleteMany({});
});
after(async () => {
  await mongoose.disconnect();
});

test('crée un client valide', async () => {
  const c = await Client.create({ nom: 'Alice', email: 'alice@exemple.com' });
  assert.ok(c._id);
});

Migrer entre versions de Mongoose

Avant une montée de version majeure : sauvegarder la base, lire le guide de migration de Mongoose, exécuter les tests. Points fréquents depuis les versions 6 et 7 :

Changement	Action
Fonctions de rappel (callbacks) retirées	Utiliser `await` ou `.then()`
`strictQuery` désactivé par défaut	Filtres avec champs non déclarés acceptés ; `mongoose.set('strictQuery', true)` pour l’ancien comportement
Options `useNewUrlParser`, `useUnifiedTopology` retirées	Les supprimer de `connect()`
`findOneAndUpdate` : option `new`	`returnDocument: 'after'` (équivalent)
`remove()` retiré	`deleteOne()` / `deleteMany()`

npm outdated mongoose
npm install mongoose@latest
npm test

Ubuntu 24.04 et 26.04 : différences à connaître

Les diagnostics sont identiques sur les deux versions. Vérifier le nom du service MongoDB (mongod) et la version du serveur installé (voir MongoDB : installation).

Pour aller plus loin

Guide de migration de Mongoose
Retour : Installation et connexion