hashicorp/nomad · error

error

Error message

%s error: %w

What it means

sendVolumeRPC wraps any error returned by the node-local host volume RPC (NodeRpc) with the RPC method name as prefix (%s error: %w). This is a wrapper: the underlying cause (transport failure, client-side handler error, session issue) is preserved via %w and should be unwrapped. It tells you which host-volume method (Create/Register/Delete) failed on the client.

Solutions

1. Unwrap the error (errors.Unwrap / %v print) to see the root cause from the client RPC.
2. Check the target client's nomad agent logs for the corresponding host-volume handler error.
3. Verify the host volume path exists and the nomad agent has permissions on the client.
4. Retry the operation; if the session was transiently broken the agent re-establishes it.

Example fix

// Go caller: unwrap to root cause
if err := c.Create(args, vol); err != nil {
    log.Printf("root cause: %v", errors.Unwrap(err))
}

err := c.Create(args, vol)
if err != nil {
    var root error = err
    for errors.Unwrap(root) != nil { root = errors.Unwrap(root) }
    log.Printf("host volume %s failed: %v", method, root)
    if isTransient(root) { retry(method, args, vol) }
}

When it happens

Trigger: Calling host volume Create, Register, or Delete where the target node is local (no forwarding needed) and the NodeRpc call to the client fails: client RPC handler error, closed yamux session, network interruption, or the client rejects the operation.

Common situations: Host volume directory does not exist / permission denied on the client; client agent restarting mid-RPC; network partition between server and client; invalid volume arguments rejected by the node plugin handler.

Related errors

• all servers should be running version
• could not place volume
• all servers must be running version
• all servers should be running version
• can't cancel terminal deployment

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

Appendix: source

Thrown at nomad/client_host_volume_endpoint.go:93

	snap, err := c.srv.State().Snapshot()
	if err != nil {
		return err
	}

	_, err = getNodeForRpc(snap, nodeID)
	if err != nil {
		return err
	}

	// Get the connection to the client
	state, ok := c.srv.getNodeConn(nodeID)
	if !ok {
		return findNodeConnAndForward(c.srv, nodeID, fwdMethod, args, reply)
	}

	// Make the RPC
	if err := NodeRpc(state.Session, method, args, reply); err != nil {
		return fmt.Errorf("%s error: %w", method, err)
	}
	return nil
}

View on GitHub (pinned to 482b49bf1a)