rcp.connection_write_timeout must be greater than zero

Error message

rcp.connection_write_timeout must be greater than zero

What it means

Returned by RPCConfig.Validate() in command/agent/config.go when rpc.connection_write_timeout is negative. This timeout bounds how long the agent waits to write to an RPC connection; the validator rejects only negative durations at config load time. The 'rcp.' prefix in the message is a typo for 'rpc.'.

Source

Thrown at command/agent/config.go:965

	if rpc.DialTimeoutHCL != "" {
		result.DialTimeoutHCL = rpc.DialTimeoutHCL
	}
	if rpc.DialTimeout > 0 {
		result.DialTimeout = rpc.DialTimeout
	}
	return &result
}

func (r *RPCConfig) Validate() error {
	if r != nil {
		if r.AcceptBacklog < 0 {
			return errors.New("rcp.accept_backlog interval must be greater than zero")
		}
		if r.KeepAliveInterval < 0 {
			return errors.New("rcp.keep_alive_interval must be greater than zero")
		}
		if r.ConnectionWriteTimeout < 0 {
			return errors.New("rcp.connection_write_timeout must be greater than zero")
		}
		if r.StreamCloseTimeout < 0 {
			return errors.New("rcp.stream_close_timeout must be greater than zero")
		}
		if r.StreamOpenTimeout < 0 {
			return errors.New("rcp.stream_open_timeout must be greater than zero")
		}
		if r.DialTimeout < 0 {
			return errors.New("rpc.dial_timeout must be greater than or equal to zero")
		}
	}

	return nil
}

// RaftBoltConfig is used in servers to configure parameters of the boltdb
// used for raft consensus.
type RaftBoltConfig struct {

View on GitHub (pinned to 482b49bf1a)

Solutions

Set rpc.connection_write_timeout to zero or a positive duration (e.g. "10s")
Remove the field to fall back to the default write timeout
Correct any automation that computes this timeout so it never emits negatives

Example fix

// before
rpc { connection_write_timeout = -10s }
// after
rpc { connection_write_timeout = 10s }

Defensive patterns

Strategy: validation

Validate before calling

if cfg.RPC != nil && cfg.RPC.ConnectionWriteTimeout < 0 {
	return fmt.Errorf("rpc.connection_write_timeout must be >= 0")
}

Type guard

func validWriteTimeout(r *RPCConfig) bool {
	return r == nil || r.ConnectionWriteTimeout >= 0
}

Try / catch

if err := rpcCfg.Validate(); err != nil {
	if strings.Contains(err.Error(), "connection_write_timeout") {
		rpcCfg.ConnectionWriteTimeout = 10 * time.Second
	}
	return err
}

Prevention

Treat all rpc timeouts as non-negative durations; drop the key for defaults
Run `nomad agent` config validation in pipelines before rollout
Avoid computing timeouts from values that can go negative (e.g. subtractions)

When it happens

Trigger: Setting `rpc { connection_write_timeout = -1s }` in server/client agent config, or building RPCConfig programmatically with a negative ConnectionWriteTimeout before calling Validate().

Common situations: Mistyped duration values in agent configs; templating systems interpolating negative values; misunderstanding that a negative value disables the timeout (it does not — omit or use zero instead).

Understand the failure class

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

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/ccafc9a806f5d7dc. Report an issue: GitHub.