hashicorp/nomad · error

rcp.stream_open_timeout must be greater than zero

Error message

rcp.stream_open_timeout must be greater than zero

What it means

Returned by RPCConfig.Validate() in command/agent/config.go when rpc.stream_open_timeout is negative. This timeout bounds how long the agent waits for a stream handshake to open; Validate() rejects negative durations when the agent config is loaded. The 'rcp.' prefix in the message is a typo for 'rpc.'.

Source

Thrown at command/agent/config.go:971

	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.
	//
	// Default: false.
	NoFreelistSync bool `hcl:"no_freelist_sync"`

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set rpc.stream_open_timeout to zero or a positive duration (e.g. "10s")
2. Remove the key so the default timeout applies
3. Audit config-templating code to ensure it cannot render negative durations

Example fix

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

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

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

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

When it happens

Trigger: Setting `rpc { stream_open_timeout = -1s }` in agent config, or instantiating RPCConfig with a negative StreamOpenTimeout in code that runs Validate() prior to launching the agent.

Common situations: Typo'd signs in duration configs; infrastructure-as-code templates rendering negative numbers; users trying to disable the timeout with -1 instead of zero or omitting the key.

Understand the failure class

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

Related errors

• rcp.connection_write_timeout must be greater than zero
• rcp.stream_close_timeout must be greater than zero
• rcp.accept_backlog interval must be greater than zero
• rcp.keep_alive_interval must be greater than zero
• missing datacenter for client registration

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