hashicorp/nomad · error

rcp.accept_backlog interval must be greater than zero

Error message

rcp.accept_backlog interval must be greater than zero

What it means

Returned by RPCConfig.Validate() in command/agent/config.go when the agent config's rpc.accept_backlog is negative. The validator only rejects values < 0; zero and positives pass. The message text is misleading ('interval', though it is a backlog size) and the 'rcp' prefix is a historical typo for 'rpc'.

Source

Thrown at command/agent/config.go:959

	if rpc.StreamCloseTimeoutHCL != "" {
		result.StreamCloseTimeoutHCL = rpc.StreamCloseTimeoutHCL
	}
	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")
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set rpc.accept_backlog to a non-negative integer (0 or greater)
2. Remove the explicit value to use Nomad's default backlog size
3. If a template computed the value, fix the expression so it cannot go negative

Example fix

// before (HCL)
rpc {
  accept_backlog = -1
}
// after
rpc {
  accept_backlog = 128
}

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

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

if err := rpcCfg.Validate(); err != nil {
	if strings.Contains(err.Error(), "accept_backlog") {
		rpcCfg.AcceptBacklog = 128 // reset to safe default
	}
	return err
}

When it happens

Trigger: Setting `rpc { accept_backlog = -1 }` (or any negative value) in an agent config file, via -rpc-accept-backlog style CLI flags mapped into RPCConfig, or programmatically building a Config with a negative AcceptBacklog before agent startup.

Common situations: Copy-pasted config snippets with negative values; templating/config management (HCL/JSON templates) computing an expression that evaluates negative; hand-editing configs assuming the field accepts -1 as 'unlimited'.

Related errors

• rcp.keep_alive_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/d545508167b21d4f. Report an issue: GitHub.