hashicorp/nomad · error

Unexpected nil volume returned for ID: %v

Error message

Unexpected nil volume returned for ID: %v

What it means

After a successful claim RPC, the hook expects the server response to carry the claimed CSIVolume. If the server returns success but resp.Volume is nil, the client treats this as an unexpected/invalid server response and fails the claim. It is a defensive check against a server/client version mismatch or inconsistent server state.

Source

Thrown at client/allocrunner/csi_hook.go:329

			AllocationID:   c.alloc.ID,
			NodeID:         c.alloc.NodeID,
			ExternalNodeID: result.stub.ExternalNodeID,
			Claim:          claimType,
			AccessMode:     request.AccessMode,
			AttachmentMode: request.AttachmentMode,
			WriteRequest: structs.WriteRequest{
				Region:    c.alloc.Job.Region,
				Namespace: c.alloc.Job.Namespace,
				AuthToken: c.nodeSecret,
			},
		}

		resp, err := c.claimWithRetry(req)
		if err != nil {
			return fmt.Errorf("could not claim volume %s: %w", req.VolumeID, err)
		}
		if resp.Volume == nil {
			return fmt.Errorf("Unexpected nil volume returned for ID: %v", request.Source)
		}

		result.volume = resp.Volume

		// populate data we'll write later to disk
		result.stub.VolumeID = resp.Volume.ID
		result.stub.VolumeNamespace = resp.Volume.Namespace
		result.stub.VolumeExternalID = resp.Volume.RemoteID()
		result.stub.PluginID = resp.Volume.PluginID
		result.publishContext = resp.PublishContext
	}

	return nil
}

func (c *csiHook) mountVolumes(results map[string]*volumePublishResult) error {

	for _, result := range results {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check Nomad client/server version compatibility — upgrade the server if the client expects the volume to be returned in the claim response.
2. Inspect server logs for the volume-claim RPC to find why the response omitted the volume.
3. Verify volume integrity: `nomad volume status <volume_id>`; re-register the volume if server state is inconsistent.
4. File a bug with Nomad if the server consistently returns a nil volume on a successful claim.

// after claim RPC, guard the response before using it
if resp == nil || resp.Volume == nil {
    return fmt.Errorf("server returned no volume for claim")
}

func hasVolume(resp *structs.CSIVolumeClaimResponse) bool {
    return resp != nil && resp.Volume != nil && resp.Volume.ID != ""
}

if err == nil && resp.Volume == nil {
    // treat as server/client version mismatch: log and retry or upgrade server
}

When it happens

Trigger: claimWithRetry returns a nil-error response whose Volume field is nil — a malformed or unexpected server reply for the volume identified by request.Source (the volume's source name in the jobspec).

Common situations: Running a newer client against an older Nomad server (or vice versa) where the claim handler doesn't populate the volume in the response; corrupted server state store for the volume; custom patches/proxies altering the RPC response.

Related errors

• could not claim volume %s: %w
• no such plugin
• could not create snapshot: %v
• error parsing: root should be an object
• missing policy name

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