Slik løser du MongoDB nettverksavbrudd i Mongoose-tilkoblingen

Den viktigste løsningen er å slutte å behandle alle Mongoose-tidsavbrudd som et problem med tidsavbruddsinnstillinger. En melding som MongoServerSelectionError: connection timed out betyr vanligvis at MongoDB-driveren ikke klarte å velge en brukbar server før serverSelectionTimeoutMS utløp. MongoDBs gjeldende feilsøkingsdokumentasjon lister nettverkstilkobling, Atlas IP-tilgangsbegrensninger, DNS SRV-feil og TLS-konfigurasjon som vanlige årsaker. Å øke tidsavbruddet kan få applikasjonen til å vente lenger uten å reparere noen av disse tilstandene.

Bruk denne rekkefølgen i stedet: 1) identifiser hvilket tidsavbrudd som feilet, 2) bevis at applikasjonsverten kan nå MongoDB, 3) korriger tilkoblingsstrengen eller den miljøspesifikke adressen, og 4) juster tidsavbruddsverdier kun etter at tilkoblingen er kjent for å fungere. Eksemplene nedenfor bruker moderne Mongoose-tilkoblingsmønstre og gjeldende MongoDB-driveratferd dokumentert i september 2026.

Først, vit hvilket tidsavbrudd du ser på

Mongoose bruker MongoDB Node.js-driveren under panseret, så flere ulike tidsavbruddsinnstillinger kan vises i samme tilkoblingskonfigurasjon. De betyr ikke det samme.

Mongoses gjeldende tilkoblingsdokumentasjon angir at serverSelectionTimeoutMS har en standardverdi på 30 sekunder og gjelder både for initial mongoose.connect() og for senere operasjoner som trenger å velge en server. MongoDBs Node.js driver tilkoblingsalternativer dokumentasjon skiller denne verdien fra connectTimeoutMS og socketTimeoutMS.

Et servervalg-tidsavbrudd er symptomet som bør klassifiseres først; feildetaljene og den underliggende årsaken er mer nyttige enn å umiddelbart øke 30-sekunders grensen.

Steg 1: fang den nøyaktige Mongoose-feilen og dens underliggende årsak

Start med en minimal tilkobling og logg nok informasjon til å skille mellom DNS-, autentiserings-, TLS- og tilgjengelighetsfeil:

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 verdien ovenfor er et diagnostisk valg, ikke en produksjonsanbefaling for alle utplasseringer. Mongoose sier at å redusere serverSelectionTimeoutMS kan gi raskere tilbakemelding, men advarer spesifikt mot å redusere den tilfeldig for replikasett fordi standardvinduet på 30 sekunder kan hjelpe operasjoner med å overleve valg og feiloverføringer. Mongoose foreslår kortere verdier mer villig for standalone MongoDB eller serverløse kjøretider der rask feiling er nyttig.

Se etter ledetråder som:

• getaddrinfo ENOTFOUND — DNS-navnet kan ikke løses.
• ECONNREFUSED — noe aktivt avviste TCP-tilkoblingen, ofte fordi ingenting lytter på verten/porten.
• ETIMEDOUT — tilkoblingsforsøket fullførte ikke i tide, ofte fordi trafikk er filtrert, feilroutet, eller destinasjonen er utilgjengelig.
• TLS- eller sertifikattekst — undersøk sertifikatstillo, vertsnavnssamsvar, protokollstøtte eller TLS-konfigurasjon.
• Autentiseringsfeil inne i err.reason — fiks legitimasjon eller authSource i stedet for å endre nettverkstidsavbrudd.

Betingelse: hvis feilen allerede sier at autentisering feilet, hopp over brannmurtuning til legitimasjon og autentiseringsdatabasen er korrekt. Et nettverkstidsavbrudd og et avvist pålogging er ulike feilklasser.

Steg 2: bevis nettverk, Atlas IP-tilgang og DNS fra samme kjøretid

Kjør tilkoblingstester fra samme maskin, container, VM, serverløse funksjon eller Kubernetes-pod der Node.js-prosessen kjører. Å teste fra bærbar PC er ikke nok hvis produksjonen kjører et annet sted.

For Atlas, verifiser at applikasjonens virkelige utgående IP er tillatt; for en lokal utplassering, verifiser at MongoDB-prosessen faktisk lytter på det forventede grensesnittet og porten.

Hvis du bruker MongoDB Atlas

Atlas aksepterer klienttilkoblinger kun fra adresser tillatt av prosjektets IP-tilgangsliste. MongoDB dokumenterer dette i Administrer IP-tilgangslisten. Sørg for at den offentlige utgående IP-en til applikasjonsmiljøet er listet, ikke bare IP-en til din personlige arbeidsstasjon.

MongoDBs feilsøkingsguide for servervalg-tidsavbrudd anbefaler også å sjekke utgående TCP-tilkobling til MongoDB på port 27017, sammen med brannmurer, sikkerhetsgrupper, nettverks-ACL-er, VPN-er og proxyer.

For eksempel, fra Linux eller macOS kan du teste en spesifikk Atlas-node eller selvadministrert vert med:

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

På Windows PowerShell er en grov TCP-tilgjengelighetstest:

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

En vellykket TCP-test beviser ikke at autentisering eller TLS vil lykkes, men en mislykket TCP-test betyr at Mongoose-tidsavbruddstuning er for tidlig.

Hvis URI-en din bruker mongodb+srv://

En SRV-tilkoblingsstreng avhenger av DNS SRV-poster. MongoDBs gjeldende feilsøkingstrinn anbefaler å sjekke SRV-oppslaget fra klientmiljøet:

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

Hvis SRV-forespørselen feiler, bekreft vertsnavnet og DNS-konfigurasjonen. MongoDB dokumenterer en ikke-SRV mongodb:// tilkoblingsstreng som en mulig omveg når miljøet ikke kan løse SRV-poster, men du bør skaffe den standard tilkoblingsstrengen fra Atlas eller din utplasseringskonfigurasjon i stedet for å finne opp nodenavn. Se Atlas tilkoblingsfeilsøking.

Den korrekte diagnostiske sekvensen sjekker adressen og nettverksstien før tidsavbruddsverdier behandles som rotårsaken.

Steg 3: fiks URI-en for miljøet der Node.js faktisk kjører

En syntaktisk gyldig MongoDB URI kan fortsatt peke til feil sted. Sjekk skjemaet, vertsnavnet, porten, databasenavnet, replikasett-kravene, autentiseringskilden, og om vertsnavnet er meningsfullt fra applikasjonens nettverksnavnerom.

Lokal Node.js og lokal MongoDB

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

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

Årsaken er Node.js 18 og nyere: Mongoose merker at Node.js kan løse localhost til IPv6 ::1, mens en lokal MongoDB-instans kanskje bare lytter på IPv4. Mongoose dokumenterer også { family: 4 } som et alternativ når IPv6-først-oppløsning gjør tilkoblingsforsøk trege:

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

Bruk family: 4 kun når IPv4/IPv6-oppløsingsstien faktisk er problemet. Hvis MongoDB-utplasseringen din støtter IPv6 korrekt, er det unødvendig å tvinge IPv4.

Node.js inne i Docker

Hvis applikasjonen er inne i en container, refererer localhost til den containeren, ikke automatisk til MongoDB på verten eller i en annen container. Bruk MongoDB-tjenesten/containerens vertsnavn på et delt Docker-nettverk, eller den plattforms-spesifikke vertadressen når MongoDB kjører på verten.

For eksempel, med en Compose-tjeneste navnet mongo:

MONGODB_URI=mongodb://mongo:27017/myapp

Betingelse: dette eksemplet gjelder kun hvis containerne deler et nettverk og MongoDB-tjenesten faktisk er navnet mongo. Ikke kopier vertsnavnet til en urelatert utplassering.

Atlas

Bruk tilkoblingsstrengen generert av Atlas for driveren din, behold mongodb+srv://-verten nøyaktig, URL-kod reserverte tegn i brukernavn eller passord når nødvendig, og verifiser at databasebrukeren finnes i det tiltenkte prosjektet.

Hvis du kobler til et selvadministrert replikasett, må vertsnavnene rapportert av replikasettet også være tilgjengelige fra klienten. En seed-vert kan være tilgjengelig mens senere servervalg fortsatt feiler fordi replikasett-medlemmer annonserer vertsnavn som applikasjonen ikke kan løse eller route til.

Steg 4: juster tidsavbrudd kun etter at tilkoblingen lykkes

Når DNS løses, nettverksstien fungerer, serveren er tilgjengelig, og URI-en er korrekt, blir tidsavbruddstuning meningsfull.

Mongoose sender tidsavbrudd-relaterte tilkoblingsalternativer til den underliggende MongoDB-driveren, men hvert alternativ styrer et annet stadium; større verdier bør ikke brukes til å skjule en ødelagt rute eller utilgjengelig server.

Et konservativt eksempel for en applikasjon som ønsker et 10-sekunders initialt feilsignal kan se slik ut:

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

Om 10 sekunder er passende avhenger av utplasseringen. Avveiningen er rett frem:

For socketTimeoutMS, bruker gjeldende MongoDB Node.js driver dokumentasjon en standardverdi på 0, som betyr ingen socket-inaktivitetstidsavbrudd. MongoDB anbefaler, når du velger å sette den, å velge en verdi omtrent to til tre ganger lengre enn den tregeste operasjonen du forventer. Denne innstillingen gjelder sockets som allerede er tilkoblet, så det er ikke den primære fiksen for et initialt servervalg-tidsavbrudd.

Ikke kopier gamle Mongoose tilkoblingsalternativer inn i et gjeldende prosjekt

Mange eldre eksempler inneholder fortsatt useNewUrlParser, useUnifiedTopology, keepAlive, eller keepAliveInitialDelay. Gjeldende Mongoose krever ikke de gamle parser/topologi opt-in-ene, og Mongoose dokumenterer keepAlive som aktivert som standard siden Mongoose 5.2 og utfaset som et tilkoblingsalternativ siden 7.2.

En moderne baseline er bevisst liten:

import mongoose from 'mongoose';

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

Legg til tilkoblingsalternativer fordi miljøet ditt trenger dem, ikke fordi de dukket opp i et fem år gammelt utdrag.

Hva om tilkoblingen fungerer, men spørringer tidsavbrytes senere?

Det er et annet problem. Hvis mongoose.connect() lykkes og applikasjonen henger på spørringer senere, undersøk operasjonslatens, tilkoblingspool-press, serverbelastning, indekser, og socket- eller operasjonstidsavbrudd. MongoDBs gjeldende Node.js driver skiller mellom:

• serverSelectionTimeoutMS — finne en passende server.
• connectTimeoutMS — etablere én TCP-tilkobling.
• socketTimeoutMS — inaktivitet på en etablert socket.
• maxTimeMS — begrense hvor lenge en serveroperasjon kan kjøre når den først når MongoDB.

Hvis kun lange spørringer feiler, er det usannsynlig at å øke serverSelectionTimeoutMS løser det virkelige problemet.

Rask diagnose etter feiltilstand

Et produksjonsvennlig tilkoblingsmønster

Hold hemmeligheter ute av kildekoden, feil oppstart tydelig når databasen er utilgjengelig, og logg nok detalj for diagnose uten å skrive ut legitimasjon:

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 verdiene samsvarer med gjeldende dokumenterte standardverdier, så du kan utelate dem med mindre å gjøre policyen eksplisitt hjelper driften din. Det viktige er ikke tallene; det er å vite hvorfor et annet tall ville vært bedre for din utplassering.

Endelig sjekkliste

• Fang den komplette feilen og inspiser err.reason.
• Bekreft at MongoDB-utplasseringen kjører og er tilgjengelig.
• Kjør DNS- og TCP-tester fra samme miljø som Node.js-prosessen.
• For Atlas, verifiser at applikasjonens utgående IP er på IP-tilgangslisten.
• For mongodb+srv://, verifiser SRV DNS-oppløsning.
• For lokal MongoDB, prøv 127.0.0.1 hvis localhost løser til ubrukelig IPv6.
• For Docker eller Kubernetes, bruk et vertsnavn som er gyldig inne i det nettverksnavnerommet.
• Fiks TLS- eller autentiseringsfeil i stedet for å maskere dem med et større tidsavbrudd.
• Juster serverSelectionTimeoutMS, connectTimeoutMS, eller socketTimeoutMS kun for stadiet de faktisk styrer.
• Etter fiksen, verifiser at applikasjonen kobler til konsistent fra det virkelige utplasseringsmiljøet, ikke bare fra en utviklerbærbar PC.

Konklusjon

Hvis Mongoose rapporterer et MongoDB nettverkstidsavbrudd, bevis først at driveren kan oppdage og nå en passende MongoDB-server. Atlas IP-begrensninger, brannmurer, DNS SRV-oppløsning, feil container vertsnavn, IPv4/IPv6-mismatch, utilgjengelige MongoDB-prosesser, og TLS-konfigurasjon kan alle få et 30-sekunders tidsavbrudd til å se ut som problemet når timeren bare rapporterer feilen.

Bruk tidsavbruddsinnstillinger til å definere hvor lenge applikasjonen din skal vente på et kjent god system – ikke til å kompensere for en ødelagt tilkoblingssti. Når nettverkstilgjengelighet og URI-en er korrekt, velg tidsavbruddsverdier som samsvarer med din tilgjengelighetsmodell, feiloverføringsatferd, og forventet operasjonslatens.