What causes "node required" in rqlite/rqlite?

Start the node with an explicit -node-id flag.

ErrNodeIDRequired

ErrNodeIDRequired

Error message

node required

What it means

ErrNodeIDRequired (cluster/join.go:16) is returned by Joiner.Do when the id parameter is an empty string. A join request must identify the joining node, so Joiner refuses to send a join with a blank node ID.

Source

Thrown at cluster/join.go:16

package cluster

import (
	"context"
	"errors"
	"log"
	"os"
	"time"

	"github.com/rqlite/rqlite/v10/cluster/proto"
	command "github.com/rqlite/rqlite/v10/command/proto"
)

var (
	// ErrNodeIDRequired is returned a join request doesn't supply a node ID
	ErrNodeIDRequired = errors.New("node required")

	// ErrJoinFailed is returned when a node fails to join a cluster
	ErrJoinFailed = errors.New("failed to join cluster")

	// ErrJoinCanceled is returned when a join operation is canceled
	ErrJoinCanceled = errors.New("join operation canceled")

	// ErrNotifyFailed is returned when a node fails to notify another node
	ErrNotifyFailed = errors.New("failed to notify node")
)

// Joiner executes a node-join operation.
type Joiner struct {
	numAttempts     int
	attemptInterval time.Duration

	client *Client
	creds  *proto.Credentials

View on GitHub (pinned to 7586a4d1bd)

Solutions

Start the node with an explicit -node-id flag.
If calling Joiner.Do programmatically, pass a non-empty unique id.
Check for empty environment-variable-derived node ID before launch.

Example fix

// before
rqlited -join leader.example.com:4001 data
// ErrNodeIDRequired: node required

// after
rqlited -node-id node1 -join leader.example.com:4001 data

Defensive patterns

Strategy: validation

Validate before calling

if id == "" {
    return "", errors.New("node ID must be non-empty before calling Joiner.Do")
}

Try / catch

if _, err := joiner.Do(ctx, addrs, id, addr, suffrage); errors.Is(err, cluster.ErrNodeIDRequired) {
    log.Fatal("start node with an explicit -node-id")
}

Prevention

Always pass -node-id when using -join
Fail fast at config parsing if node ID is empty
Avoid deriving node ID from potentially empty env vars without a default

When it happens

Trigger: Calling Joiner.Do(ctx, targetAddrs, "", addr, suffrage) — i.e. passing an empty id — which happens upstream when rqlited is started without -node-id while joining a cluster that requires node IDs.

Common situations: Running rqlited with -join but forgetting -node-id in newer versions where node IDs are mandatory for joins; scripting the join API and omitting the id field.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of rqlite/rqlite@7586a4d1bd (2026-09-03). Data as JSON: /api/errors/66df92f6a62e88b0. Report an issue: GitHub.