What causes "raft.intra_rpc_port must be greater than 0" in weaviate/weaviate?

Set raft.intra_rpc_port (yaml) or RAFT_INTERNAL_RPC_PORT env var to a valid port, e.g. 7001

raft.intra_rpc_port must be greater than 0

Error message

raft.intra_rpc_port must be greater than 0

What it means

Configuration validation error: the raft.join list contains the same node entry more than times than one. Duplicate join targets would create ambiguous cluster membership, so validation rejects the configuration at startup.

Source

Thrown at usecases/config/config_handler.go:1203

	DrainSleep         *runtime.DynamicValue[time.Duration]

	ConsistencyWaitTimeout time.Duration

	BootstrapTimeout   time.Duration
	BootstrapExpect    int
	MetadataOnlyVoters bool

	EnableOneNodeRecovery bool
	ForceOneNodeRecovery  bool
}

func (r *Raft) Validate() error {
	if r.Port == 0 {
		return fmt.Errorf("raft.port must be greater than 0")
	}

	if r.InternalRPCPort == 0 {
		return fmt.Errorf("raft.intra_rpc_port must be greater than 0")
	}

	uniqueMap := make(map[string]struct{}, len(r.Join))
	updatedJoinList := make([]string, len(r.Join))
	for i, nodeNameAndPort := range r.Join {
		// Check that the format is correct. In case only node name is present we append the default raft port
		nodeNameAndPortSplitted := strings.Split(nodeNameAndPort, ":")
		if len(nodeNameAndPortSplitted) == 0 {
			return fmt.Errorf("raft.join element %s has no node name", nodeNameAndPort)
		} else if len(nodeNameAndPortSplitted) < 2 {
			// If user only specify a node name and no port, use the default raft port
			nodeNameAndPortSplitted = append(nodeNameAndPortSplitted, fmt.Sprintf("%d", DefaultRaftPort))
		} else if len(nodeNameAndPortSplitted) > 2 {
			return fmt.Errorf("raft.join element %s has unexpected amount of element", nodeNameAndPort)
		}

		// Check that the node name is unique
		nodeName := nodeNameAndPortSplitted[0]

View on GitHub (pinned to 75aa4b6d11)

Solutions

Set raft.intra_rpc_port (yaml) or RAFT_INTERNAL_RPC_PORT env var to a valid port, e.g. 7001
Ensure each raft node's config defines both raft.port and raft.intra_rpc_port
Review the multi-node setup docs to confirm all required raft ports are set

Example fix

// before
raft:
  port: 7000
// after
raft:
  port: 7000
  intra_rpc_port: 7001

Defensive patterns

Strategy: validation

Validate before calling

if raftEnabled {
  if raftPort == 0 || internalRPCPort == 0 {
    panic("RAFT_PORT and RAFT_INTERNAL_RPC_PORT must both be set when raft is enabled")
  }
}

Try / catch

err := server.Start()
if err != nil && strings.Contains(err.Error(), "intra_rpc_port must be greater than 0") {
  // surface which env var is missing: RAFT_INTERNAL_RPC_PORT
}

Prevention

Always configure raft.port and raft.intra_rpc_port as a pair
Pick non-overlapping defaults (e.g. 7000/7001) in your deployment templates
Check for partially exported RAFT_* env var sets before startup

When it happens

Trigger: Starting Weaviate with raft enabled without setting raft.intra_rpc_port / RAFT_INTERNAL_RPC_PORT, leaving the default 0.

Common situations: Configuring raft.port but forgetting the companion internal RPC port; copying a partial raft config from docs or a colleague; env-var-only setups where only some RAFT_* vars are exported.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/15bd3c596854839e. Report an issue: GitHub.