hashicorp/nomad · error

missing stagingTargetPath

Error message

missing stagingTargetPath

What it means

NodeUnstageVolume in the Nomad CSI client wrapper returns this sentinel error before issuing the gRPC call when the stagingTargetPath argument is an empty string. Like the sibling 'missing volumeID' check, it is a development-time aid that prevents sending a malformed NodeUnstageVolumeRequest to the CSI plugin. It indicates the caller lost track of the staging path for the volume claim.

Source

Thrown at plugins/csi/client.go:834

		case codes.Internal:
			err = fmt.Errorf("node plugin returned an internal error, check the plugin allocation logs for more information: %v", err)
		}
	}

	return err
}

func (c *client) NodeUnstageVolume(ctx context.Context, volumeID string, stagingTargetPath string, opts ...grpc.CallOption) error {
	if err := c.ensureConnected(ctx); err != nil {
		return err
	}
	// These errors should not be returned during production use but exist as aids
	// during Nomad development
	if volumeID == "" {
		return fmt.Errorf("missing volumeID")
	}
	if stagingTargetPath == "" {
		return fmt.Errorf("missing stagingTargetPath")
	}

	req := &csipbv1.NodeUnstageVolumeRequest{
		VolumeId:          volumeID,
		StagingTargetPath: stagingTargetPath,
	}

	// NodeUnstageVolume's response contains no extra data. If err == nil, we were
	// successful.
	_, err := c.nodeClient.NodeUnstageVolume(ctx, req, opts...)
	if err != nil {
		code := status.Code(err)
		switch code {
		case codes.NotFound:
			err = fmt.Errorf("%w: volume %q could not be found: %v",
				structs.ErrCSIClientRPCIgnorable, volumeID, err)
		case codes.Internal:
			err = fmt.Errorf("node plugin returned an internal error, check the plugin allocation logs for more information: %v", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Pass the same staging target path that was used in the matching NodeStageVolume call
2. Ensure the volume claim/persisted state records StagingTargetPath before unstage
3. Verify the client volume stanza and hook wiring populate the path on restore
4. If the volume was never staged, skip the unstage call instead of calling it with an empty path

Example fix

// before
csi.Client.NodeUnstageVolume(ctx, volumeID, "")
// after
if stagingPath == "" {
	return fmt.Errorf("cannot unstage volume %q: staging path unknown", volumeID)
}
csi.Client.NodeUnstageVolume(ctx, volumeID, stagingPath)

if stagingTargetPath == "" {
	return fmt.Errorf("cannot unstage volume %q: stagingTargetPath is empty", volumeID)
}
// proceed to client.NodeUnstageVolume(ctx, volumeID, stagingTargetPath)

func hasStagingPath(p string) bool { return strings.TrimSpace(p) != "" }

err := client.NodeUnstageVolume(ctx, volumeID, stagingPath)
if err != nil && strings.Contains(err.Error(), "missing stagingTargetPath") {
	// developer-aid error: log and skip or recover the path from claim state
	logger.Warn("unstage skipped: empty stagingTargetPath", "volume", volumeID)
	return nil
}
return err

When it happens

Trigger: Calling client.NodeUnstageVolume(ctx, volumeID, "") with an empty staging path — e.g. when the task's volume staging directory path was not persisted with the claim or was cleared during agent state restoration.

Common situations: Host-volume staging directory configuration changes between runs; restoring node state after a crash where the staging path in the claim struct was empty; hand-written code against the CSI client that omits StagingTargetPath.

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

• missing volumeID
• %w: volume %q could not be found: %v
• validation error: %v
• volume row conversion error
• structs.ErrUnknownAllocationPrefix

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