Sådan løser du MongoDB-netværkstidsudløbsfejl i Mongoose-forbindelsen

Den vigtigste løsning er at stoppe med at behandle alle Mongoose-tidsudløb som et problem med tidsudløbsindstillinger. En besked som MongoServerSelectionError: connection timed out betyder normalt, at MongoDB-driveren ikke kunne vælge en brugbar server, før serverSelectionTimeoutMS udløb. MongodB's aktuelle fejlfindingsdokumentation nævner netværksforbindelser, Atlas IP-adgangsrestriktioner, DNS SRV-fejl og TLS-konfiguration som almindelige årsager. At øge tidsudløbet kan få applikationen til at vente længere uden at reparere nogen af disse tilstande.

Brug denne rækkefølge i stedet: 1) identificer hvilket tidsudløb der fejlede, 2) bevis at applikationsværten kan nå MongoDB, 3) korriger forbindelsesstrengen eller den miljøspecifikke adresse, og 4) juster tidsudløbsværdier kun efter at forbindelsen er kendt for at virke. Eksemplerne nedenfor bruger moderne Mongoose-forbindelsesmønstre og nuværende MongoDB-driveradfærd dokumenteret i september 2026.

Først, vid hvilket tidsudløb du kigger på

Mongoose bruger MongoDB Node.js-driveren under overfladen, så flere forskellige tidsudløbsindstillinger kan optræde i samme forbindelseskonfiguration. De betyder ikke det samme.

MongodB's nuværende forbindelsesdokumentation angiver, at serverSelectionTimeoutMS som standard er 30 sekunder og gælder både for den indledende mongoose.connect() og for senere operationer, der skal vælge en server. MongoDB's Node.js driver forbindelsesmuligheder dokumentation skelner denne værdi fra connectTimeoutMS og socketTimeoutMS.

Et servervalg-tidsudløb er det symptom, der skal klassificeres først; fejlens detaljer og den underliggende årsag er mere nyttige end straks at øge 30-sekunders grænsen.

Trin 1: Fang den præcise Mongoose-fejl og dens underliggende årsag

Start med en minimal forbindelse og log nok information til at skelne mellem DNS-, godkendelses-, TLS- og tilgængelighedsfejl:

import mongoose from 'mongoose';

try {
  await mongoose.connect(process.env.MONGODB_URI, {
    serverSelectionTimeoutMS: 5000
  });

  console.log('MongoDB connected');
} catch (err) {
  console.error(err);
  console.error('Reason:', err.reason);
  process.exit(1);
}

5-sekunders værdien ovenfor er et diagnostisk valg, ikke en produktionsanbefaling for alle implementeringer. Mongoose siger, at reduktion af serverSelectionTimeoutMS kan give hurtigere feedback, men advarer specifikt mod at reducere det tilfældigt for replikasæt, fordi standardvinduet på 30 sekunder kan hjælpe operationer med at overleve valg og failovers. Mongoose foreslår kortere værdier mere villigt for standalone MongoDB eller serverløse runtime-miljøer, hvor hurtig fejlfinding er nyttig.

Se efter spor som:

• getaddrinfo ENOTFOUND — DNS-navnet kan ikke løses.
• ECONNREFUSED — noget afviste aktivt TCP-forbindelsen, ofte fordi intet lytter på værten/porten.
• ETIMEDOUT — forbindelsesforsøget blev ikke fuldført i tide, ofte fordi trafikken er filtreret, dirigeret forkert eller destinationen er utilgængelig.
• TLS- eller certifikattekst — undersøg certifikattillid, værtsnavnsmatch, protokolunderstøttelse eller TLS-konfiguration.
• Godkendelsesfejl inde i err.reason — ret legitimationsoplysninger eller authSource i stedet for at ændre netværkstidsudløb.

Betingelse: Hvis fejlen allerede siger, at godkendelsen fejlede, så spring firewalljustering over, indtil legitimationsoplysningerne og godkendelsesdatabasen er korrekte. Et netværkstidsudløb og et afvist login er forskellige fejltyper.

Trin 2: Bevis netværk, Atlas IP-adgang og DNS fra samme runtime

Kør tilgængelighedstests fra den samme maskine, container, VM, serverløse funktion eller Kubernetes-pod, hvor Node.js-processen kører. At teste fra din bærbare computer er ikke nok, hvis produktionen kører et andet sted.

For Atlas, verificér at applikationens faktiske udgående IP er tilladt; for en lokal implementering, verificér at MongoDB-processen faktisk lytter på det forventede interface og port.

Hvis du bruger MongoDB Atlas

Atlas accepterer kun klientforbindelser fra adresser, der er tilladt af projektets IP-adgangsliste. MongoDB dokumenterer dette i Administrer IP-adgangslisten. Sørg for, at den offentlige udgående IP for applikationsmiljøet er angivet, ikke blot din personlige arbejdsstations IP.

MongoDB's fejlfindingsvejledning for servervalg-tidsudløb anbefaler også at tjekke udgående TCP-forbindelse til MongoDB på port 27017, sammen med firewalls, sikkerhedsgrupper, netværks-ACL'er, VPN'er og proxyer.

Fra Linux eller macOS kan du for eksempel teste en specifik Atlas-node eller selvforvaltet vært med:

nc -vz your-mongodb-host.example.com 27017

På Windows PowerShell er en grov TCP-tilgængelighedstest:

Test-NetConnection your-mongodb-host.example.com -Port 27017

En vellykket TCP-test beviser ikke, at godkendelse eller TLS vil lykkes, men en mislykket TCP-test betyder, at Mongoose-tidsudløbsjustering er for tidlig.

Hvis din URI bruger mongodb+srv://

En SRV-forbindelsesstreng afhænger af DNS SRV-poster. MongoDB's nuværende fejlfindingstrin anbefaler at tjekke SRV-opslaget fra klientmiljøet:

nslookup -type=SRV _mongodb._tcp.cluster-name.mongodb.net

Hvis SRV-forespørgslen fejler, skal du bekræfte værtsnavnet og DNS-konfigurationen. MongoDB dokumenterer en ikke-SRV mongodb:// forbindelsesstreng som en mulig workaround, når miljøet ikke kan løse SRV-poster, men du skal hente den standard forbindelsesstreng fra Atlas eller din implementeringskonfiguration i stedet for at opfinde nodenavne. Se Atlas forbindelsesfejlfinding.

Den korrekte diagnostiske rækkefølge tjekker adressen og netværksstien, før tidsudløbsværdier behandles som den underliggende årsag.

Trin 3: Ret URI'en for det miljø, hvor Node.js faktisk kører

En syntaktisk gyldig MongoDB URI kan stadig pege på det forkerte sted. Tjek skemaet, værtsnavnet, porten, databasenavnet, replikasætkrav, godkendelseskilden og om værtsnavnet er meningsfuldt fra applikationens netværksnavnerum.

Lokal Node.js og lokal MongoDB

Mongoose anbefaler i øjeblikket 127.0.0.1 i stedet for localhost for lokal MongoDB:

await mongoose.connect('mongodb://127.0.0.1:27017/myapp');

Årsagen er Node.js 18 og nyere: Mongoose bemærker, at Node.js kan løse localhost til IPv6 ::1, mens en lokal MongoDB-instans måske kun lytter på IPv4. Mongoose dokumenterer også { family: 4 } som en mulighed, når IPv6-første opløsning gør forbindelsesforsøg langsomme:

await mongoose.connect('mongodb://localhost:27017/myapp', {
  family: 4
});

Brug family: 4 kun, når IPv4/IPv6-opløsningsstien faktisk er problemet. Hvis din MongoDB-implementering understøtter IPv6 korrekt, er det unødvendigt at tvinge IPv4.

Node.js inde i Docker

Hvis applikationen er inde i en container, refererer localhost til den container, ikke automatisk til MongoDB på værten eller i en anden container. Brug MongoDB-tjenesten/containerens værtsnavn på et delt Docker-netværk, eller den platformspecifikke værtsadresse, når MongoDB kører på værten.

For eksempel, med en Compose-tjeneste navngivet mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Betingelse: Dette eksempel gælder kun, hvis containerne deler et netværk, og MongoDB-tjenesten faktisk er navngivet mongo. Kopier ikke værtsnavnet til en urelateret implementering.

Atlas

Brug forbindelsesstrengen genereret af Atlas til din driver, bevar mongodb+srv://-værten præcist, URL-kod reserverede tegn i brugernavne eller adgangskoder, når det er nødvendigt, og verificér at databasebrugeren findes i det tilsigtede projekt.

Hvis du opretter forbindelse til et selvforvaltet replikasæt, skal værtsnavnene rapporteret af replikasættet også være tilgængelige fra klienten. En seed-vært kan være tilgængelig, mens senere servervalg stadig fejler, fordi replikasætsmedlemmer annoncerer værtsnavne, som applikationen ikke kan løse eller dirigere til.

Trin 4: Juster tidsudløb kun efter at forbindelsen lykkes

Når DNS løses, netværksstien virker, serveren er tilgængelig, og URI'en er korrekt, bliver tidsudløbsjustering meningsfuld.

Mongoose sender tidsudløbsrelaterede forbindelsesmuligheder til den underliggende MongoDB-driver, men hver mulighed styrer et andet trin; større værdier bør ikke bruges til at skjule en brudt rute eller utilgængelig server.

Et konservativt eksempel for en applikation, der ønsker et 10-sekunders indledende fejlsignal, kunne se sådan ud:

await mongoose.connect(process.env.MONGODB_URI, {
  serverSelectionTimeoutMS: 10000,
  connectTimeoutMS: 10000
});

Om 10 sekunder er passende, afhænger af implementeringen. Afvejningen er ligetil:

For socketTimeoutMS bruger den nuværende MongoDB Node.js-driver-dokumentation en standard på 0, hvilket betyder ingen socket-inaktivitetstidsudløb. MongoDB anbefaler, når du vælger at indstille det, at vælge en værdi, der er cirka to til tre gange længere end den langsomste operation, du forventer. Denne indstilling gælder for sockets, der allerede er tilsluttet, så det er ikke den primære løsning på et indledende servervalg-tidsudløb.

Kopier ikke gamle Mongoose-forbindelsesmuligheder til et nuværende projekt

Mange ældre eksempler indeholder stadig useNewUrlParser, useUnifiedTopology, keepAlive eller keepAliveInitialDelay. Nuværende Mongoose kræver ikke de gamle parser/topologi-opt-ins, og Mongoose dokumenterer keepAlive som aktiveret som standard siden Mongoose 5.2 og deprecieret som en forbindelsesmulighed siden 7.2.

En moderne baseline er bevidst lille:

import mongoose from 'mongoose';

await mongoose.connect(process.env.MONGODB_URI);

Tilføj forbindelsesmuligheder, fordi dit miljø har brug for dem, ikke fordi de optrådte i et fem år gammelt uddrag.

Hvad hvis forbindelsen virker, men forespørgsler udløber senere?

Det er et andet problem. Hvis mongoose.connect() lykkes, og applikationen senere hænger på forespørgsler, så undersøg operationsforsinkelse, forbindelsespool-tryk, serverbelastning, indeks og socket- eller operationstidsudløb. MongoDB's nuværende Node.js-driver adskiller:

• serverSelectionTimeoutMS — finde en passende server.
• connectTimeoutMS — etablere én TCP-forbindelse.
• socketTimeoutMS — inaktivitet på et etableret socket.
• maxTimeMS — begrænse hvor længe en serveroperation må køre, når den først når MongoDB.

Hvis kun lange forespørgsler fejler, er det usandsynligt, at øgning af serverSelectionTimeoutMS løser det reelle problem.

Hurtig diagnose efter fejltilstand

Et produktionsvenligt forbindelsesmønster

Hold hemmeligheder ude af kildekoden, fejle opstart tydeligt, når databasen er utilgængelig, og log nok detaljer til diagnose uden at udskrive legitimationsoplysninger:

import mongoose from 'mongoose';

export async function connectDatabase() {
  const uri = process.env.MONGODB_URI;

  if (!uri) {
    throw new Error('MONGODB_URI is not set');
  }

  try {
    await mongoose.connect(uri, {
      serverSelectionTimeoutMS: 30000,
      connectTimeoutMS: 30000
    });

    console.log('MongoDB connected');
  } catch (err) {
    console.error('MongoDB connection failed:', err.message);
    console.error('Server selection reason:', err.reason);
    throw err;
  }
}

Disse 30-sekunders værdier matcher de nuværende dokumenterede standarder, så du kan udelade dem, medmindre det at gøre politikken eksplicit hjælper dine operationer. Det vigtige er ikke tallene; det er at vide, hvorfor et andet tal ville være bedre for din implementering.

Endelig tjekliste

• Fang den fulde fejl og undersøg err.reason.
• Bekræft at MongoDB-implementeringen kører og er tilgængelig.
• Kør DNS- og TCP-tests fra samme miljø som Node.js-processen.
• For Atlas, verificér at applikationens udgående IP er på IP-adgangslisten.
• For mongodb+srv://, verificér SRV DNS-opløsning.
• For lokal MongoDB, prøv 127.0.0.1, hvis localhost løser til ubrugelig IPv6.
• For Docker eller Kubernetes, brug et værtsnavn, der er gyldigt inde i det netværksnavnerum.
• Ret TLS- eller godkendelsesfejl i stedet for at maskere dem med et større tidsudløb.
• Juster serverSelectionTimeoutMS, connectTimeoutMS eller socketTimeoutMS kun for det trin, de faktisk styrer.
• Efter løsningen, verificér at applikationen opretter forbindelse konsistent fra det rigtige implementeringsmiljø, ikke kun fra en udviklerbærbar computer.

Konklusion

Hvis Mongoose rapporterer et MongoDB-netværkstidsudløb, skal du først bevise, at driveren kan opdage og nå en passende MongoDB-server. Atlas IP-restriktioner, firewalls, DNS SRV-opløsning, forkerte containerværtsnavne, IPv4/IPv6-mismatch, utilgængelige MongoDB-processer og TLS-konfiguration kan alle få et 30-sekunders tidsudløb til at se ud som problemet, når timeren kun rapporterer fejlen.

Brug tidsudløbsindstillinger til at definere, hvor længe din applikation skal vente på et kendt-godt system – ikke til at kompensere for en brudt forbindelsessti. Når netværkstilgængelighed og URI'en er korrekte, skal du derefter vælge tidsudløbsværdier, der matcher din tilgængelighedsmodel, failover-adfærd og forventede operationsforsinkelse.