Decommissioning iSCSI Storage and Avoiding APD/PDL Conditions

Products

• VMware vCenter Server
• VMware vSphere ESXi 8.0

Issue/Introduction

ESXi hosts experience persistent All Paths Down (APD) alerts when decommissioning iSCSI static targets. While the device remains stable when set to offline, the process of detaching the device or removing the static target causes the ESXi host to administratively turn the device back ON, triggering a path failure during the removal sequence.

Symptoms

• hostd.log shows: Event 1022075 : Device naa.####, has been turned on administratively.
• vmkernel.log reports NMP: nmp_ThrottleLogForDevice:###: Cmd 0x0... Failed followed by StorageApdHandler: ###: APD start.
• Setting the device state to off completes without error, but subsequent removal steps trigger the alarm.
• Initiator may attempt to reconnect sessions immediately after removal, leading to re-discovery.

Environment

• VMware vSphere ESXi 7.x, 8.x
• iSCSI Storage using Static or Dynamic Discovery

Cause

The ESXi Pluggable Storage Architecture (PSA) continues to probe registered devices to monitor their state. When a static target is removed while the device is still registered in the PSA database, the host attempts to re-verify the path, causing it to flip the administrative state to ON. Since the session is simultaneously being terminated, the commands fail, resulting in an APD event.

Resolution

To decommission iSCSI storage without triggering an APD, select one of the following methods:

Option 1: Storage-Side PDL Trigger (Recommended)

This method forces a Permanent Device Loss (PDL) state, which ESXi handles as a planned disconnection rather than a failure.

1. Identify Target Details: Before removal, run the following command to identify the correct Target_IQN and Target_IP: esxcli iscsi adapter target portal list
   

2. Set State to Off: Administratively disable the device on the ESXi host: esxcli storage core device set --state=off -d <Device_ID>

3. Unmap at Storage Array: Remove the LUN mapping from the storage array. The host will receive a SCSI Sense Code indicating the device is gone (PDL).

4. Remove Target: esxcli iscsi adapter discovery statictarget remove -A <vmhba> -n <Target_IQN> -a <Target_IP>

   
     

Option 2: Temporary Autoclaim Disable

Use this method if the initiator continues to re-claim the device during removal.

1. Set State to Off: esxcli storage core device set --state=off -d <Device_ID>

2. Disable Autoclaim: esxcli storage core claiming autoclaim --enabled=false
   ⚠️ IMPORTANT: This is a system-wide setting. Re-enable it immediately after the rescan to avoid impacting new LUN discoveries.
   

3. Unclaim the Device: esxcli storage core claiming autoclaim -t device -d <Device_ID>


4. Remove from Target and Rescan: Unmap the device from Storage array and perform a storage rescan. 

5. Re-Enable Autoclaim: esxcli storage core claiming autoclaim --enabled=true
   
   

Option 3: Temporary vCenter Alarm Suppression

If CLI methods are restricted, suppress vCenter alarms to prevent false positives during maintenance.

1. Suppress Alarms: Follow the procedure in How to disable an alarm of specific ESXi host  to disable "Host Connection and power state" or specific storage connectivity alarms for the affected host.

2. Proceed with Standard Detach: Unmount the datastore, detach the device, and remove the iSCSI target portals.

3. Restore Alarms: Re-enable the alarm definitions once decommissioning is confirmed.

Additional Information

• To speak with a customer representative or a Support Engineer see Contact Support. Scroll to the bottom of the page and click on your respective region.
• Removing a LUN containing a datastore from VMware ESXi/ESX
• Detach a LUN device from ESXi hosts