nats-io/nats-server · error

timeout after %v: request type %q on %q: got %d out of %d

Error message

timeout after %v: request type %q on %q: got %d out of %d

What it means

Multi-response variant of the JSAPI request timeout: the MQTT adapter requested N responses (e.g. expecting replies from multiple nodes/consumers) but only got some within the timeout, so it reports how many of the expected responses arrived. Indicates partial responsiveness of the JetStream layer.

Source

Thrown at server/mqtt.go:1754

			c++
			if c == len(msgs) {
				return responses, nil
			}

		case <-jsa.quitCh:
			return nil, ErrServerNotRunning

		case <-t.C:
			var reply string
			now := time.Now()
			for reply = range r2i { // preserve the last value for Errorf
				jsa.replies.Delete(reply)
			}

			if len(msgs) == 1 {
				return responses, fmt.Errorf("timeout after %v: request type %q on %q (reply=%q)", now.Sub(start), kind, subject, reply)
			} else {
				return responses, fmt.Errorf("timeout after %v: request type %q on %q: got %d out of %d", now.Sub(start), kind, subject, c, len(msgs))
			}
		}
	}
}

func (jsa *mqttJSA) sendAck(ackSubject string) {
	// Send to the ack subject with no payload.
	jsa.sendMsg(ackSubject, nil)
}

func (jsa *mqttJSA) sendMsg(subj string, msg []byte) {
	if subj == _EMPTY_ {
		return
	}
	// We pass -1 for the hdr so that the send loop does not need to
	// add the "client info" header. This is not a JS API request per se.
	jsa.sendq.push(&mqttJSPubMsg{subj: subj, msg: msg, hdr: -1})
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Restore unhealthy cluster members or fix the network partition so all JS peers respond
2. Check nats server report jetstream for lagging replicas and restart/replace them
3. Retry the operation once the cluster is fully healthy
4. Raise server resources if nodes are too slow to answer within the timeout

// Verify all JS peers respond before partial-response-prone operations:
for _, s := range nc.Servers() {
    // check each server's JS enabled/healthy state via monitoring endpoint /jsz
}

if strings.Contains(err.Error(), "got ") && strings.Contains(err.Error(), "out of ") {
    // partial responses: identify lagging replicas and retry after recovery
    return retryWithBackoff(op)
}

When it happens

Trigger: A JS API request expecting multiple replies (c counter vs len(msgs)) times out with partial responses received — e.g. some cluster members respond, others are slow/down.

Common situations: Degraded cluster: some JS peers down or partitioned; uneven load causing some nodes to respond after the deadline; consumer fan-out requests on a partially healthy stream.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• timeout after %v: request type %q on %q (reply=%q)
• no interest
• no flow response
• JS_CONSUMER_OFFLINE
• shutting down

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/90ef8d63ef796152. Report an issue: GitHub.