nats-io/nats-server · error

timeout after %v: request type %q on %q (reply=%q)

Error message

timeout after %v: request type %q on %q (reply=%q)

What it means

This is the single-response variant of the internal JSAPI request timeout in the MQTT JetStream adapter. A request (stream lookup, create, update, consumer create, etc.) was sent on an internal reply subject and no response arrived within the timeout; when exactly one reply inbox was registered the error reports the reply subject for debugging.

Source

Thrown at server/mqtt.go:1752

			i := r2i[r.reply]
			responses[i] = r
			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.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check JetStream cluster health and wait for leader elections to settle, then retry
2. Increase server capacity or reduce load; timeouts under heavy load are the usual cause
3. Investigate network partition/latency between clustered servers
4. If timeouts are systemic, review jetstream configuration and client reconnect/backoff behavior

// Pre-check JS API responsiveness:
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_, err := js.AccountInfo(nats.Context(ctx))
// err on timeout means JS API is slow — do not start MQTT workload yet

if strings.Contains(err.Error(), "timeout after") && strings.Contains(err.Error(), "request type") {
    // exponential backoff retry; check cluster health before next attempt
    return retryWithBackoff(op)
}

When it happens

Trigger: JetStream API slow or unresponsive (leader election, overloaded server, no responders); request timeout exceeded while waiting for a single JS API response during MQTT setup operations (lookupStream, createStream, updateStream, createEphemeralConsumer).

Common situations: Under-provisioned servers under load; JetStream raft elections in progress; network partition in a cluster; very large meta state slowing JS API responses.

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: got %d out of %d
• no interest
• no flow response
• ack wait must be a positive value
• JS API timeout must be a positive value

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