What causes "rcp.stream_close_timeout must be greater than zero" in hashicorp/nomad?

Set rpc.stream_close_timeout to zero or a positive duration (e.g. "5m")

rcp.stream_close_timeout must be greater than zero

Error message

rcp.stream_close_timeout must be greater than zero

What it means

Returned by RPCConfig.Validate() in command/agent/config.go when rpc.stream_close_timeout is negative. This timeout governs how long an RPC stream may remain open before being closed; only negative values are rejected at agent startup. The message's 'rcp.' prefix is a typo for 'rpc.'.

Source

Thrown at command/agent/config.go:968

	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 {
	// NoFreelistSync toggles whether the underlying raft storage should sync its
	// freelist to disk within the bolt .db file. When disabled, IO performance
	// will be improved but at the expense of longer startup times.

View on GitHub (pinned to 482b49bf1a)

Solutions

Set rpc.stream_close_timeout to zero or a positive duration (e.g. "5m")
Omit the field to use the built-in default
Fix templating logic that could produce negative values

Example fix

// before
rpc { stream_close_timeout = -5m }
// after
rpc { stream_close_timeout = 5m }

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

if err := rpcCfg.Validate(); err != nil {
	if strings.Contains(err.Error(), "stream_close_timeout") {
		rpcCfg.StreamCloseTimeout = 5 * time.Minute
	}
	return err
}

Prevention

Express 'long-lived streams' with a large positive duration, never a negative one
Add config schema checks to IaC that render rpc blocks
Keep an example rpc block in docs with only valid positive durations

When it happens

Trigger: Configuring `rpc { stream_close_timeout = -30s }` in agent config or constructing RPCConfig with a negative StreamCloseTimeout and invoking Validate() before starting the agent.

Common situations: Hand-edited HCL/JSON configs with sign typos; config generators producing negative durations; attempts to express 'never close' with a negative number instead of a very large duration or omitting the setting.

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/16f61205de961295. Report an issue: GitHub.