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.

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)

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.