What causes "connection pool exhausted" in micro/go-micro?

Increase the pool size in the broker configuration to match peak concurrency.

ErrPoolExhausted

ErrPoolExhausted

Error message

connection pool exhausted

What it means

ErrPoolExhausted is a sentinel error returned by the NATS connectionPool's Get when every connection in the pool is checked out and none are available. The pool is bounded (a fixed-size channel of connections), so concurrent demand above the pool size yields this error instead of blocking indefinitely.

Solutions

Increase the pool size in the broker configuration to match peak concurrency.
Ensure every code path that Get()s a connection returns it with pool.Put(), including error paths.
Retry with backoff — connections are returned as concurrent operations complete.

Defensive patterns

Strategy: validation

Validate before calling

if err == natsbroker.ErrPoolExhausted {
    // increase pool size or retry with backoff
}

Try / catch

sub, err := b.Subscribe(topic, handler)
if errors.Is(err, natsbroker.ErrPoolExhausted) {
    time.Sleep(backoff)
    sub, err = b.Subscribe(topic, handler)
}

Prevention

Size the pool at or above peak concurrent subscriber operations.
Always release pooled connections on every code path (defer pool.Put).
Watch for error repeats under load as a signal to raise pool capacity.

When it happens

Trigger: Calling pool.Get() (via Subscribe) when the connections channel is empty — more concurrent operations than pool capacity, or connections leaked (never Put back after a panic or early return).

Common situations: High-concurrency subscribers exceeding the configured pool size; leaked connections from error paths that skip releasing; benchmarks/load tests with many goroutines sharing one broker instance.

Related errors

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/077381ddba1da700. Report an issue: GitHub.

Appendix: source

Thrown at broker/nats/pool.go:13

package nats

import (
	"errors"
	"sync"
	"time"

	natsp "github.com/nats-io/nats.go"
)

var (
	// ErrPoolExhausted is returned when no connections are available in the pool
	ErrPoolExhausted = errors.New("connection pool exhausted")
	// ErrPoolClosed is returned when trying to use a closed pool
	ErrPoolClosed = errors.New("connection pool is closed")
)

// connectionPool manages a pool of NATS connections
type connectionPool struct {
	mu          sync.RWMutex
	connections chan *pooledConnection
	factory     func() (*natsp.Conn, error)
	size        int
	idleTimeout time.Duration
	closed      bool
}

// pooledConnection wraps a NATS connection with metadata
type pooledConnection struct {
	conn      *natsp.Conn
	createdAt time.Time

View on GitHub (pinned to 24529f1404)