Atlas error: connection refused under load on shared tiers

Not specified by the original author.

TL;DR: Free and Flex tiers cap connections. When the app scales, new connections get refused. Check the Connections metric against the tier limit. Fix, in order 1.

The error

text
the app connects fine at low traffic, then under load new connections fail or hang. The Atlas Connections metric is flat at the tier cap.

The fix

TL;DR: Free and Flex tiers cap connections. When the app scales, new connections get refused. Check the Connections metric against the tier limit. Fix, in order 1.

The error

the app connects fine at low traffic, then under load new connections fail or hang. The Atlas Connections metric is flat at the tier cap.

The fix

1. Check the Connections metric against the tier limit. Free (M0) and Flex clusters have low caps; this is by design.
2. Count clients: instances x pools, plus any per-request client creation bug, plus open mongosh sessions and tools.
3. One client per process, small pools on serverless (1 to 5). Most "limit" problems are actually client-count bugs.
4. Close idle clients and sessions; check for leaked cursors holding connections.
5. Only then move to a dedicated tier (M10+) if genuine concurrent demand exceeds the cap. The Flex tier replaced the old M2/M5 and serverless instance types; check current limits for your tier before assuming.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas error.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Atlas tier structure (Free, Flex, Dedicated) and the retirement of M2/M5 and serverless instances per https://www.mongodb.com/docs/atlas/manage-flex-clusters/ and https://mongodb.com/docs/atlas/flex-migration/, verified 2026-09-26.