What causes "Failed to encode request: %v" in hashicorp/nomad?

Check cluster version skew and upgrade servers to matching Nomad versions

Failed to encode request: %v

Error message

Failed to encode request: %v

What it means

raftApplyFuture encodes a message (type + payload) with structs.Encode before writing it to the raft log. If the message cannot be messagepack-encoded, raft is never touched and this error is returned. It almost always indicates a malformed or unencodable payload rather than a cluster problem.

Source

Thrown at nomad/rpc.go:792

	var ack structs.StreamingRpcAck
	if err := decoder.Decode(&ack); err != nil {
		conn.Close()
		return nil, err
	}

	if ack.Error != "" {
		conn.Close()
		return nil, errors.New(ack.Error)
	}

	return conn, nil
}

// raftApplyFuture is used to encode a message, run it through raft, and return the Raft future.
func (s *Server) raftApplyFuture(t structs.MessageType, msg any) (raft.ApplyFuture, error) {
	buf, err := structs.Encode(t, msg)
	if err != nil {
		return nil, fmt.Errorf("Failed to encode request: %v", err)
	}

	// Warn if the command is very large
	if n := len(buf); n > raftWarnSize {
		s.logger.Warn("attempting to apply large raft entry", "raft_type", t, "bytes", n)
	}

	future := s.raft.Apply(buf, enqueueLimit)
	return future, nil
}

// raftApplyFn is the function signature for applying a msg to Raft
type raftApplyFn func(t structs.MessageType, msg any) (any, uint64, error)

// raftApply is used to encode a message, run it through raft, and return the
// FSM response along with any errors. If the FSM.Apply response is an error it
// will be returned as the error return value with a nil response.
func (s *Server) raftApply(t structs.MessageType, msg any) (any, uint64, error) {

View on GitHub (pinned to 482b49bf1a)

Solutions

Check cluster version skew and upgrade servers to matching Nomad versions
Inspect server logs for the wrapped encode error to identify the offending struct
Fix the caller building the malformed message (e.g. nil/unsupported fields)
Reproduce with a minimal payload to isolate which field fails messagepack encoding

Example fix

// before
req := &structs.JobRegisterRequest{Job: nil}
_, err := srv.raftApply(structs.JobRegisterRequestType, req)
// after
req := &structs.JobRegisterRequest{Job: validJob, WriteRequest: structs.WriteRequest{Region: region}}
_, err := srv.raftApply(structs.JobRegisterRequestType, req)

Defensive patterns

Strategy: validation

Validate before calling

buf, err := structs.Encode(t, msg)
if err != nil {
    return fmt.Errorf("refusing raft apply, unencodable payload: %w", err)
}

Try / catch

future, err := srv.raftApplyFuture(t, msg)
if err != nil && strings.Contains(err.Error(), "Failed to encode request") {
    return fmt.Errorf("payload for %s not encodable; check for nil/unsupported fields: %w", t, err)
}

Prevention

Keep server/client versions aligned to avoid unknown struct fields
Reject nil or partially initialized request structs before raft apply
Add encode smoke tests for custom message types

When it happens

Trigger: raftApply/applyPlan submitting a message whose contents cannot be encoded — unsupported types, corrupted/nil nested structs, or version skew where a struct contains fields the encoder of this server cannot handle.

Common situations: Version-skewed clusters where a newer client submits structs with unknown fields; forked code adding unencodable types; corrupted request objects from buggy callers of raftApply.

Related errors

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