**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
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

```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

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.