volume %q already exists but is incompatible with these para

Error message

volume %q already exists but is incompatible with these parameters: %v

What it means

ControllerCreateVolume got gRPC code AlreadyExists from the CSI plugin: a volume with the requested name/ID is already present but its existing properties don't match the requested parameters. Nomad surfaces this so the operator knows reuse was refused rather than silently proceeding with an incompatible existing volume.

Source

Thrown at plugins/csi/client.go:447

	creq := req.ToCSIRepresentation()
	resp, err := c.controllerClient.CreateVolume(ctx, creq, opts...)

	// these standard gRPC error codes are overloaded with CSI-specific
	// meanings, so translate them into user-understandable terms
	// https://github.com/container-storage-interface/spec/blob/master/spec.md#createvolume-errors
	if err != nil {
		code := status.Code(err)
		switch code {
		case codes.InvalidArgument:
			return nil, fmt.Errorf(
				"volume %q snapshot source %q is not compatible with these parameters: %v",
				req.Name, req.ContentSource, err)
		case codes.NotFound:
			return nil, fmt.Errorf(
				"volume %q content source %q does not exist: %v",
				req.Name, req.ContentSource, err)
		case codes.AlreadyExists:
			return nil, fmt.Errorf(
				"volume %q already exists but is incompatible with these parameters: %v",
				req.Name, err)
		case codes.ResourceExhausted:
			return nil, fmt.Errorf(
				"unable to provision %q in accessible_topology: %v",
				req.Name, err)
		case codes.OutOfRange:
			return nil, fmt.Errorf(
				"unsupported capacity_range for volume %q: %v", req.Name, err)
		case codes.Internal:
			return nil, fmt.Errorf(
				"controller plugin returned an internal error, check the plugin allocation logs for more information: %v", err)
		}
		return nil, err
	}

	return NewCreateVolumeResponse(resp), nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Check the existing volume's parameters in the backend and update the Nomad volume spec to match them.
Delete the conflicting backend volume if it is unused, then retry creation.
Use a different volume name/ID if you genuinely want a new, distinct volume.
Run `nomad volume status` and `nomad volume deregister` to clear stale registrations before recreating.

Example fix

// before (spec asks 20GiB, backend volume is 10GiB)
size = 20
// after (match existing volume)
size = 10

Defensive patterns

Strategy: validation

Validate before calling

// Check for an existing conflicting volume before creating
existing, _ := findBackendVolumeByName(req.Name)
if existing != nil && !paramsMatch(existing, requestedParams) {
    return fmt.Errorf("volume %s exists with different params; reconcile spec or rename", req.Name)
}

Type guard

func canReuseVolume(existing *csi.Volume, req *csi.CreateVolumeRequest) bool {
    return existing != nil && existing.CapacityBytes >= req.CapacityRange.RequiredBytes
}

Try / catch

vol, err := client.ControllerCreateVolume(ctx, req)
if err != nil && strings.Contains(err.Error(), "already exists but is incompatible") {
    // adopt matching params or delete/rename the existing volume, then retry
}

Prevention

Deregister stale volumes (`nomad volume deregister`) before recreating with new parameters.
Keep volume specs in version control so parameters stay consistent across recreations.
Use unique volume names per environment to avoid collisions.

When it happens

Trigger: Calling ControllerCreateVolume where the backend already has a volume with req.Name (or the derived external ID) but with different capacity, capabilities, or topology than requested, causing the plugin to return codes.AlreadyExists.

Common situations: Re-registering a volume in Nomad after the backend volume was created with different parameters; stale volume from a previous job; cluster migration where the same external volume ID exists with a different size.

Related errors

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