NATS Go ConnPool exhaustion returns ErrPoolEmpty immediately without blocking option

Direct answer

No supported blocking option exists for NATS Go ConnPool. NextConnection returns ErrPoolEmpty immediately when MaxConnections connections are checked out and none are idle. The API exposes no wait, timeout, or queue parameter, so a caller cannot block until a connection is released through pool configuration alone.

Likely explanation versus facts pending verification

Likely explanation: ConnPool is a bounded connection checkout pool, not a blocking work queue. Adding wait-or-timeout semantics would be an API change rather than a configuration toggle.

Facts requiring verification against your pinned build:

• The research brief indicates immediate non-blocking exhaustion across NATS Go client 1.x and 2.x releases.
• The brief notes that the concrete error type and message for exhaustion have drifted between minor versions.
• No confirmed stability guarantee for the exhaustion error type across minor releases has been identified.

Steps for this case

1. Pin the NATS Go module in go.mod and record the exact major and minor version.
2. Inspect the exported sentinel for your build: go doc github.com/nats-io/nats.go/v2 ConnPool ErrPoolEmpty (use the v1 module path if you are on v1).
3. Handle ErrPoolEmpty at the caller level with sleep and backoff, or bound concurrency with a semaphore before calling NextConnection. Avoid tight retry loops without sleeping.
4. If the pool limit is too low, raise MaxConnections and return every checked-out connection promptly through the same logical operation that checked it out.
5. Re-test exhaustion error handling after any minor NATS Go upgrade; do not assume the same error type or message persists.

Verification

Run go doc against your pinned module to confirm NextConnection has no wait, timeout, or queue parameter. Grep the local module cache for ErrPoolEmpty to confirm the exact exported symbol in your version. To observe saturation, check out MaxConnections connections, call NextConnection, and measure elapsed time; an immediate return confirms non-blocking exhaustion.

Missing diagnostic detail

Which major and minor version of github.com/nats-io/nats.go are you pinned to? The correct errors.Is or errors.As target depends on that build, and it changes the error-handling recommendation.

Assumption: this concerns the NATS Go client (github.com/nats-io/nats.go or /v2), not other NATS clients. This is a conservative draft; verify error symbols and release notes against your pinned module before relying on them in production.