Failed migrations: Migrating VrfPrefixListMigrationTask" NSX upgrade failure when upgrading from 3.2.x to 4.x release

Products

• VMware NSX

Issue/Introduction

• NSX Manager dry run failed with below exception when trying to upgrade from 3.2.2 to 4.x release

  2025-10-02T20:52:37.978Z WARN pool-12-thread-1 UfoCorfuTableMigrator 29480 - [nsx@6876 comp="nsx-manager" level="WARNING" subcomp="manager"] ERROR while running logical migration MappingDetails{name='VrfPrefixList
  MigrationTask', runForTheseFromVersions='3.2,4.0', targetVersion='4.1', modelName='null', migrationType=null, reason='This migration task will run for migrations from GC/HL/3.2.0 to 4.1. It will add missing prefix
  entries to VRF.', customMigratorClassName='com.vmware.nsx.management.migration.impl.VrfPrefixListMigrationTask', fieldMappings=null, targetProtoName='null', requiresCustomCode='false', owner='null', apiToTest='null
  ', weight='1.0', impactedTables='InternalPrefixListConfig', cleanup='false', enabled'false', diskBacked'false', triggerMode'null', supportsResolve'false', component'null'}
  java.lang.NullPointerException: null
          at com.vmware.nsx.management.migration.impl.VrfPrefixListMigrationTask.migratePrefixList(VrfPrefixListMigrationTask.java:87) ~[logical-migration.jar:?]
          at com.vmware.nsx.management.migration.impl.VrfPrefixListMigrationTask.migrate(VrfPrefixListMigrationTask.java:61) ~[logical-migration.jar:?]
          at com.vmware.nsx.management.migration.ufo.UfoCorfuTableMigrator.migrate(UfoCorfuTableMigrator.java:145) ~[logical-migration.jar:?]
          at com.vmware.nsx.management.migration.ufo.UFOMigration.invokeMigrate(UFOMigration.java:256) ~[logical-migration.jar:?]
          at com.vmware.nsx.management.migration.ufo.UFOMigration.migrateData(UFOMigration.java:224) ~[logical-migration.jar:?]
          at com.vmware.nsx.management.migration.ufo.UFOMigration$1.run(UFOMigration.java:168) ~[logical-migration.jar:?]
          at java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source) ~[?:?]
          at java.util.concurrent.FutureTask.run(Unknown Source) ~[?:?]
          at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source) ~[?:?]
          at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source) ~[?:?]
          at java.lang.Thread.run(Unknown Source) ~[?:?]
  2025-10-02T20:52:37.995Z INFO pool-12-thread-1 ProgressMonitoring 29480 - [nsx@6876 comp="nsx-manager" level="INFO" subcomp="manager"] Marking task VrfPrefixListMigrationTask as failed
  2025-10-02T20:52:37.997Z WARN pool-12-thread-1 ProgressMonitoring 29480 - [nsx@6876 comp="nsx-manager" level="WARNING" subcomp="manager"] Failed to dump progress to DB due to null
  2025-10-02T20:52:37.999Z INFO pool-12-thread-1 ProgressMonitoring 29480 - [nsx@6876 comp="nsx-manager" level="INFO" subcomp="manager"] Marking task VrfPrefixListMigrationTask as done

Environment

VMware NSX 3.2.0.x
VMware NSX 3.2.2.x
VMware NSX 4.x

Cause

When a VRF prefix entry does not exist in the 'PrefixListConfig' table, and does exist within 'LogicalRouter', 'GPRR' and 'PrefixList table', the upgrade pre-check will fail. 

Resolution

This is a known issue impacting VMware NSX.

The following are the workaround options:

Option 1: 
1. The simplest workaround, for the VRF ID to which the pre-check is failing against, is to remove the VRF, if no devices are using it. 
2. Re-try the upgrade. 

Or, 

Option 2:
To note, this script can be run on NSX 3.2.x & 4.1.x version. 
1) Take a standard NSX backup and ensure the passphrase is known. 
2) Download the .jar file attached to this KB.
3)Through WinSCP, copy the .jar file and transfer to an NSX Manager (any will do).  
4) SSH to NSX manager as root user, proceed to where the .jar file location was saved to, and enter the below: 

For the version : 3.2.0.x 

# java -cp "libcorfu-data-corrector-lib.jar:/opt/vmware/proton-tomcat/webapps/nsxapi/WEB-INF/lib/*:/usr/tomcat/lib/*" -Dcorfu-property-file-path=/opt/vmware/proton-tomcat/conf/ufo-factory.properties -Djava.io.tmpdir=/image/corfu-tools/temp com.vmware.nsx.management.migration.impl.PrefixListDataCorrector

For the version : 3.2.1 & onwards

# java -cp "libcorfu-data-corrector-lib.jar:/opt/vmware/proton-tomcat/webapps/nsxapi/WEB-INF/lib/*:/usr/tomcat/lib/*" -Dcorfu-property-file-path=/opt/vmware/proton-tomcat/conf/ufo-factory.properties -Djava.io.tmpdir=/image/corfu-tools/temp com.vmware.nsx.management.migration.impl.InternalPrefixListDataCorrector

5) Once run, no output will mean a successful run.
6) A dummy update is now needed to the VRF to finalize the remediation.
On the NSX UI, go to Networking > Tier-0 Gateway > edit settings of the VRF, add any text to the Description box and click Save: 

7) Proceed with the NSX upgrade.