nsqio/nsq · error
msg timeout (%d) is invalid
Error message
msg timeout (%d) is invalid
What it means
IDENTIFY's msg_timeout field lets a client override how long nsqd waits before retrying a delivered message. clientV2.SetMsgTimeout accepts 0 (keep the --msg-timeout default, 60s) or milliseconds in [1000, --max-msg-timeout] (default 900000ms = 15m). Any other value returns this error and the IDENTIFY command fails.
Source
Thrown at nsqd/client_v2.go:581
if sampleRate < 0 || sampleRate > 99 {
return fmt.Errorf("sample rate (%d) is invalid", sampleRate)
}
atomic.StoreInt32(&c.SampleRate, sampleRate)
return nil
}
func (c *clientV2) SetMsgTimeout(msgTimeout int) error {
c.writeLock.Lock()
defer c.writeLock.Unlock()
switch {
case msgTimeout == 0:
// do nothing (use default)
case msgTimeout >= 1000 &&
msgTimeout <= int(c.nsqd.getOpts().MaxMsgTimeout/time.Millisecond):
c.MsgTimeout = time.Duration(msgTimeout) * time.Millisecond
default:
return fmt.Errorf("msg timeout (%d) is invalid", msgTimeout)
}
return nil
}
func (c *clientV2) UpgradeTLS() error {
c.writeLock.Lock()
defer c.writeLock.Unlock()
tlsConn := tls.Server(c.Conn, c.nsqd.tlsConfig)
if err := tlsConn.SetDeadline(time.Now().Add(5 * time.Second)); err != nil {
return err
}
err := tlsConn.Handshake()
if err != nil {
return err
}
c.tlsConn = tlsConnView on GitHub (pinned to 85cf10c09c)
Solutions
- Send 0 to use the server default or a millisecond value in [1000, 900000]
- If handlers legitimately run longer, raise --max-msg-timeout on nsqd (and prefer designing idempotent, quickly-acking work)
- Verify the unit is milliseconds
Example fix
// before cfg.MsgTimeout = 45 * time.Minute // 2700000ms > 15m max -> error on IDENTIFY // after cfg.MsgTimeout = 10 * time.Minute // 600000ms, within [1000,900000]
Defensive patterns
Strategy: validation
Validate before calling
func clampMsgTimeout(ms, maxMs int) int {
if ms == 0 {
return 0
}
if ms < 1000 { return 1000 }
if ms > maxMs { return maxMs }
return ms
} Try / catch
// connect-time config error: log desired vs [1000,max], fix duration, reconnect
Prevention
- Set MsgTimeout via time.Duration in client libraries, never raw ints
- Raise --max-msg-timeout on nsqd before shipping longer timeouts
- Prefer short timeouts + idempotent handlers over multi-hour attempts
When it happens
Trigger: Sending msg_timeout: 500 (below the 1s floor), msg_timeout: 3600000 for a 1h timeout when max is 15m, or a negative number.
Common situations: Long-running handlers (batch jobs, ML inference, big file processing) wanting longer than 15m per attempt; unit confusion between seconds and milliseconds; tuning copied from a cluster with a raised --max-msg-timeout.
Understand the failure class
- Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.
Related errors
AI-assisted analysis of nsqio/nsq@85cf10c09c (2026-08-16).
Data as JSON: /api/errors/729f8b5178fe26d6.
Report an issue: GitHub.