hashicorp/nomad · error

rcp.keep_alive_interval must be greater than zero

Error message

rcp.keep_alive_interval must be greater than zero

What it means

Returned by RPCConfig.Validate() in command/agent/config.go when rpc.keep_alive_interval is set to a negative value. It fires at agent startup before the RPC layer is initialized. The 'rcp.' prefix in the message is a long-standing typo for 'rpc.'; only negative values are rejected (zero passes).

Source

Thrown at command/agent/config.go:962

	if rpc.StreamCloseTimeout > 0 {
		result.StreamCloseTimeout = rpc.StreamCloseTimeout
	}
	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
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set rpc.keep_alive_interval to zero or a positive duration (e.g. "30s")
2. Omit the field entirely to use the default keep-alive interval
3. Fix any config template logic that could emit a negative duration

Example fix

// before
rpc { keep_alive_interval = -30s }
// after
rpc { keep_alive_interval = 30s }

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

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

if err := rpcCfg.Validate(); err != nil {
	if strings.Contains(err.Error(), "keep_alive_interval") {
		rpcCfg.KeepAliveInterval = 30 * time.Second
	}
	return err
}

When it happens

Trigger: Configuring `rpc { keep_alive_interval = -5s }` in the agent config or supplying a negative duration through config parsing into RPCConfig.KeepAliveInterval, then starting the agent.

Common situations: Typo'd durations in HCL/JSON agent config; environment-driven config templating producing negative durations; users attempting to disable keep-alives with a negative value instead of omitting the field.

Related errors

• rcp.accept_backlog interval must be greater than zero
• rcp.connection_write_timeout must be greater than zero
• rcp.stream_close_timeout must be greater than zero
• rcp.stream_open_timeout 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/fd7f7409cd48bcf5. Report an issue: GitHub.