Troubleshooting data migration errors in Data Virtualization

Diagnose and troubleshoot Data Virtualization export and import errors after you view the logs.

View detailed export-import logs, including errors that are logged as exceptions, in the QueryplexAdmin.log file. To access the file, navigate to /mnt/logs/diaglogs/NODE0000/QueryplexAdmin.log in the Data Virtualization head node (pod c-db2u-dv-db2u-0).

Alternatively, you can collect diagnostics. See Gathering diagnostic information.

cpd-cli migration errors

Importing multi-source nicknames causes DV Engine object import did not run successfully error
Import governance error
DV Engine object import did not run successfully error

Importing multi-source nicknames causes DV Engine object import did not run successfully error

Cause: When you import multi-source nicknames, the import fails due to an issue with the import processing of multiple source CIDs for a single nickname.

Diagnosis: Check the log /mnt/logs/diaglogs/NODE0000/QueryplexAdmin.log for objects that failed to import, based on the results of the import job.

This is an example of an import job (output from oc logs <import-job-id>) that failed to import a multi-source nickname.

In this example log, AUTHORS_SS_GRP is the failed object:

2025-11-17 16:32:58,924	ERROR	Object Schema=DB2_SINGLE_SOURCE Name=AUTHORS_SS_GRP Type=N import failed: fail -- Failed to run import SQLs for object: 'DB2_SINGLE_SOURCE:AUTHORS_SS_GRP'.
2025-11-17 16:32:58,927	ERROR	DV Engine object import did not run successfully

Workaround:

In this workaround, you will update the SQL of the failed import multi-source nickname, then re-run the SQL manually before re-running the import job with OBJ_IGNORE_DUPLICATES=true.

Get the CID mappings. From the oc logs <import-job-id>, get the controlData JSON. The JSON displayed contains a JSON array called cid_map like in this example, and you will need it for the subsequent steps.

{
  "exportIdentifier":"cpd-ex-export-20251023185029", 
  "exportDate":"2025-10-23_18-50-59", 
  "exportFormatVersion":"1.3", 
  "instanceId":"<INSTANCE_ID>", 
  "exported_cams_containers":{"catalogs":[<CATALOG_IDs>]}, 
  "connections" [
    {"sourceConnectionID":"DB210000", ..., <CONNECTION PROPERTIES>, ..., "export_status":"success",
"import_status":"success"}],
  "user_map":[],
  "objects":[
    {
      "schema":"DB2_SINGLE_SOURCE", 
      "name":"AUTHORS_SS_GRP", 
      "type":"N", 
      "export_status":"success", 
      "import_status":"fail -- Failed to run import SQLs for object: 'DB2_SINGLE_SOURCE:AUTHORS_SS_GRP'.",
      "grant_status":"aborted -- Due to earlier import issue from: Failed to run import SQLs for object: 'DB2_SINGLE_SOURCE:AUTHORS_SS_GRP'."
    }
  ],
  "useGit":false,
  "cid_map":[
    {"source_cid":"DB210000","target_cid":"DB210025"}
  ]
}

In /mnt/logs/diaglogs/NODE0000/QueryplexAdmin.log, search for the failed object by its name to find the error log.

In this example log, AUTHORS_SS_GRP is the failed object:

2025-11-17 16:32:46.899~125964661 Db2AdminImportUtils ---> Executing SQL: CREATE NICKNAME "DB2_SINGLE_SOURCE"."AUTHORS_SS_GRP" FOR "QPLEX"."GAIANDB"."AUTHORS"("AUTHOR_ID","FIRST_NAME","MIDDLE_NAME","LAST_NAME","PHONE") OPTIONS(SOURCELIST 'DB210025:"BOOK_SCHEMA",DB210000:"NEW_BOOK_SCHEMA"')
2025-11-17 16:32:47.293~520468179 ClientDatabaseMetaData -----> ******* getTables(DB210025:"BOOK_SCHEMA",DB210000:"NEW_BOOK_SCHEMA",GAIANDB,AUTHORS,null), isBypassDerbyViewsForQueryplexTables = true
2025-11-17 16:32:47.299~526105528 DVConfig --------------> ******* getTables(AUTHORS) Cache entry found with NUMSOURCES 2 (DB210025:BOOK_SCHEMA:4,DB210025:NEW_BOOK_SCHEMA:5), NUMCOLS 5 (AUTHOR_ID INTEGER, FIRST_NAME VARCHAR(100), MIDDLE_NAME VARCHAR(50), LAST_NAME VARCHAR(100), PHON...). Using cache if requested sourcelist is null or subset of cached set: false
2025-11-17 16:32:47.580~807580049 ClientDatabaseMetaData -----> ******* getTables(AUTHORS) Resolution Exception: java.lang.Exception: SQL0551N The statement failed because the authorization ID does not have the required authorization or privilege to perform the operation. Authorization ID: '<not available>'. Operation: 'CLIENT_GETTABLES_LOOKUP'. Object: 'DB210000'.
        => TRACE:     JavaFunc.getTables:-1 -> ClientDatabaseMetaData.getTables:1367 -> DVConfig.resolveRemoteTableViaCacheOrDynamic:1514
2025-11-17 16:32:47.693~920231776 Db2AdminImportUtils ---> WARNING:

2025-11-17 16:32:47.692 ********** GDB_ERROR: ERROR_IMPORT_OBJECT:-1822: Failed to import object for SQL=CREATE NICKNAME "DB2_SINGLE_SOURCE"."AUTHORS_SS_GRP" FOR "QPLEX"."GAIANDB"."AUTHORS"("AUTHOR_ID","FIRST_NAME","MIDDLE_NAME","LAST_NAME","PHONE") OPTIONS(SOURCELIST 'DB210025:"BOOK_SCHEMA",DB210000:"NEW_BOOK_SCHEMA"') with exception: Unexpected error code "" received from data source "QPLEX". Associated text and tokens are "java.lang.Exception: SQL0551N The statement failed because th".. SQLCODE=-1822, SQLSTATE=     , DRIVER=4.36.6
        com.ibm.db2.jcc.am.SqlException: Unexpected error code "" received from data source "QPLEX". Associated text and tokens are "java.lang.Exception: SQL0551N The statement failed because th".. SQLCODE=-1822, SQLSTATE=     , DRIVER=4.36.6
        => TRACE:     DB2AdminImportUtils.importObjects:259 -> DB2AdminImportUtils.importObjectsImpl:429 -> DB2AdminImportUtils.main:1153 -> DB2AdminImportUtils.createDatabaseObjectFromExportData:1541 -> DB2AdminImportUtils.runSqls:2211 -> kr.execute:1117 -> kr.e:1138 -> kr.a:3434 -> kr.ak:2207 -> au.h:124 -> p.b:38 -> aa.c:102 -> aa.k:451 -> kr.b:2212 -> kr.d:2874 -> kr.c:2890 -> b5.a:140 -> b5.a:66 -> b5.a:815
2025-11-17 16:32:47.692 Documentation: <GaianDBDocumentationDirectory>/javadoc-errors/com/ibm/gaiandb/diags/GDBMessages.html#ERROR_IMPORT_OBJECT:-1822


2025-11-17 16:32:47.694~921073238 ActivityTracker --> Check if ENABLE_AUDIT is on or off
2025-11-17 16:32:47.773~520049 Db2AdminImportUtils ---> WARNING:

2025-11-17 16:32:47.773 ********** GDB_WARNING: FAILED_OBJECT_SQLS_IMPORT: Failed to run import SQLs for object: 'DB2_SINGLE_SOURCE:AUTHORS_SS_GRP'. Exception: Non-zero return code: -1 - transactions failed.

2025-11-17 16:32:47.773 Documentation: <GaianDBDocumentationDirectory>/javadoc-errors/com/ibm/gaiandb/diags/GDBMessages.html#FAILED_OBJECT_SQLS_IMPORT

Navigate to Executing SQL: for failed object to obtain the SQL. Example:

For example, AUTHORS_SS_GRP is the failed object:

2025-11-17 16:32:46.899~125964661 Db2AdminImportUtils ---> Executing SQL: CREATE NICKNAME "DB2_SINGLE_SOURCE"."AUTHORS_SS_GRP" FOR "QPLEX"."GAIANDB"."AUTHORS"("AUTHOR_ID","FIRST_NAME","MIDDLE_NAME","LAST_NAME","PHONE") OPTIONS(SOURCELIST 'DB210025:"BOOK_SCHEMA",DB210000:"NEW_BOOK_SCHEMA"')

Check the SOURCELIST in the SQL. The previous example is incorrect based on our cid_map from earlier. Ensure that the OPTIONS (SOURCELIST...) follows this format and that all the CIDs are correctly mapped:
Note: If a CID in the SOURCELIST of a SQL does not exist in the cid_map, then the connection was not exported correctly and must be manually added to the import instance. After that, follow the same workaround steps to apply the new CID to the SOURCELIST.
```
OPTIONS (SOURCELIST '<NEW_CID>:"<SCHEMA_NAME>"[,<NEW_CID>:"<SCHEMA_NAME>,...]')
```
In this example, the SQL would change from:
```
CREATE NICKNAME "DB2_SINGLE_SOURCE"."AUTHORS_SS_GRP" FOR "QPLEX"."GAIANDB"."AUTHORS"("AUTHOR_ID","FIRST_NAME","MIDDLE_NAME","LAST_NAME","PHONE") OPTIONS(SOURCELIST 'DB210025:"BOOK_SCHEMA",DB210000:"NEW_BOOK_SCHEMA"')
```
to:
```
CREATE NICKNAME "DB2_SINGLE_SOURCE"."AUTHORS_SS_GRP" FOR "QPLEX"."GAIANDB"."AUTHORS"("AUTHOR_ID","FIRST_NAME","MIDDLE_NAME","LAST_NAME","PHONE") OPTIONS(SOURCELIST 'DB210025:"BOOK_SCHEMA",DB210025:"NEW_BOOK_SCHEMA"')
```
where you reference the cid_map to ensure that all CIDs were correctly updated:
```
        {
            "source_cid": "DB210000",
            "target_cid": "DB210025"
        }
```
This result indicates that you need to update DB210000 to DB210025 in the SOURCELIST of the SQL.

Finally, connect to the database and execute the updated SQL manually:

db2 => CREATE NICKNAME "DB2_SINGLE_SOURCE"."AUTHORS_SS_GRP" FOR "QPLEX"."GAIANDB"."AUTHORS"("AUTHOR_ID","FIRST_NAME","MIDDLE_NAME","LAST_NAME","PHONE") OPTIONS(SOURCELIST 'DB210025:"BOOK_SCHEMA",DB210025:"NEW_BOOK_SCHEMA"')

DB20000I  The SQL command completed successfully.

Re-run import with OBJ_IGNORE_DUPLICATES=true.

Example in .yaml file to be used in import:

dv-aux:
    values: '{"objectsOptions":"GOV_PROCEED_ON_ERROR=True,CONN_IGNORE_DUPLICATES=True,OBJ_IGNORE_DUPLICATES=True"}'

After you complete the workaround, run a new import job with the custom yaml specified:

cpd-cli export-import import create <cpd_import_name> \
--profile=cpadmin \
--from-export <export_data_name> \
--service-type dv \
--instance-name ${service_instance_name}  \
--namespace ${SERVICE_INSTANCE_NAMESPACE} \
--values values.yaml

Output example:

cpd-cli export-import import status import-20251117183308 --profile <PROFILE> -n <NAMESPACE>
Name:        	import-20251117183308          
Job Name:    	cpd-im                         
Active:      	0                              
Succeeded:   	1                              
Failed:      	0                              
Start Time:  	Mon, 17 Nov 2025 10:33:09 -0800
Completed At:	Mon, 17 Nov 2025 10:33:37 -0800
Duration:    	28s

Import governance error

You might encounter this governance related error during import.

ERROR: Import governance: ENSURE GOVERNANCE ARTIFACTS WERE IMPORTED FIRST -- Import executed without SKIP_GOVERNANCE=TRUE, but did not find any imported governance artifacts associated with DV instance ID '<EXPORTED_DV_INSTANCE_ID>'. Ensure that you import governance artifacts before performing DV import or execute the import with SKIP_GOVERNANCE=TRUE option

Cause: This error might occur for the following reasons.

Case 1

You might be attempting to import Data Virtualization assets before IBM® Knowledge Catalog catalog assets.
Case 2

You might be re-importing governance artifacts after it has completed successfully during a previous run.

Resolving the problem: This error might occur for the following reasons.

Case 1

Migrate governance assets separately by using the IBM Knowledge Catalog export-import module. To migrate your governance assets, see Migrating catalog assets, Migrating governance artifacts, and Migrating data protection rules.
Case 2

If there are no imported catalog, project, connection and deployment space assets to update, then run the Data Virtualization import with the SKIP_GOVERNANCE=TRUE option to skip updating these assets and to proceed with importing Data Virtualization objects. See SKIP_GOVERNANCE.

DV Engine object import did not run successfully error

When you run oc logs <import-job-id>, the following error might display when you try to re-import modified control data:

2025-03-17 19:36:42,900	ERROR	Object Schema=DV_ADMIN1 Name=ORACLETEST Type=N import failed: fail--Failed to run import SQLs for object: 'DV_ADMIN1 (schema)'.
2025-03-17 19:36:42,902	ERROR	Object Schema=DV_ENG1 Name=T1 Type=N import failed: fail--Failed to run import SQLs for object: 'DV_ENG1 (schema)'.
2025-03-17 19:36:42,951	ERROR	DV Engine object import did not run successfully

Cause: These are duplication-related errors that might occur if you were attempting to re-import your modified control data.

Resolution: If want to re-import your control data, then specify CONN_IGNORE_DUPLICATES=True and OBJ_IGNORE_DUPLICATES=True. For more information, see IGNORE_DUPLICATES.

Git migration errors

Re-importing assets with a different Git registration causes dvapi_gitintegration_runtime.GitIntegrationAPIError error

Cause: After you import your objects by using Git, you cannot safely re-import objects (or any subsequent objects) to the same target instance with a different Git registration, or this error message appears:

dvapi_gitintegration_runtime.GitIntegrationAPIError: API request failed: 
{'code': 500, 'message': 'Retrieving Git import files from Platform API: failed with exception - java.lang.Exception: Exception occurred during GET request i
n getGitPullFromPlatform. Error: getDVAPIFileResponse call failed with status: 400'}

Workaround: Contact IBM Support.