Source and classification

• Source: Customer-site Veeam integration issue.
• Classification: Uninstall residue on a specific upgrade path.
• Confirmation basis: At the site, 1.0.3 was uninstalled before 1.0.4 was installed, and installation failed. Communication confirmed that uninstalling 1.0.3 might leave ovirtadapter tables and failed database migration records, and cleanup statements were provided. If 1.0.3 has not been uninstalled, the normal 1.0.4 path is an in-place installation.
• Internal tracking: No related Jira.

Issue metadata

• Issue ID: None.
• Component/product: Veeam API Proxy.
• Status: A site remediation is available; installation and business verification must still be completed in the destination environment.
• Priority/severity: High; installation failure prevents Veeam from integrating with the platform through API Proxy.
• Affected version: Environments where API Proxy 1.0.3 was installed and uninstalled before 1.0.4 was installed.
• Confirmed environment: Site communication mentions ZSphere 5.1.0 h84r; whether this matches every affected site requires confirmation.
• Issue confirmation date: August 26, 2026.
• Last updated: September 4, 2026.

Problem description

The normal upgrade from API Proxy 1.0.3 to 1.0.4 retains 1.0.3 and runs the 1.0.4 installer to replace the old version. If a local or remote uninstall is performed first, the uninstall might not completely remove ovirtadapter database objects.

When 1.0.4 is installed again, database initialization or version migration encounters old tables and failed migration-history records, causing installation to fail. Repeated uninstall, installation, or in-place installation attempts generally do not automatically remove existing database residue.

Site communication identified these residual objects:

• zstack.ovirtadapter_snapshot_proxy_attachment;
• zstack.ovirtadapter_snapshot_session;
• Failed records in zstack.ovirtadapter_schema_history with version 8 or 9 and success = 0.

Symptoms

• API Proxy 1.0.3 was installed, then uninstalled, and installing 1.0.4 fails.
• Local uninstall, remote uninstall, and an in-place installation after uninstall do not recover it.
• Retrying repeatedly produces the same database initialization or migration error.
• The database still contains ovirtadapter_snapshot_proxy_attachment, ovirtadapter_snapshot_session, or failed version 8/9 migration records.

Use the actual site output for the exact installer error and log keywords. Do not perform this database cleanup based only on "1.0.4 installation failed."

Site screenshot

Impact

• API Proxy 1.0.4 cannot finish installation or start.
• Veeam cannot register, scan, or protect platform virtual machines.
• Repeated installation retries might increase residual state and make site diagnosis harder.
• Cleanup is a database operation. Incorrect scope or lack of a backup might cause configuration loss or make rollback impossible.

Workaround

Correct upgrade method when 1.0.3 has not been uninstalled

1. Do not uninstall 1.0.3 before upgrading to 1.0.4.
2. Save the current API Proxy configuration, installation parameters, and logs, and complete pre-upgrade checks from the 1.0.4 release notes.
3. Run the 1.0.4 installer directly for an in-place installation.
4. Verify the API Proxy process, service port, platform connection, and Veeam VM scan after installation.

When 1.0.3 was uninstalled and 1.0.4 installation failed

The following operations delete database tables and records. A database administrator or developer familiar with the site must perform them in a maintenance window. Before proceeding, confirm this version path and the residual objects and complete a usable database backup. Do not use this procedure for other API Proxy versions or installation failures whose cause is unconfirmed.

1. Stop retrying and collect information

1. Stop rerunning the 1.0.4 installer and retain complete output from the first and latest failures.
2. Collect:

• Platform version and original/target API Proxy versions;
• How and when 1.0.3 was uninstalled;
• Complete UI screenshot or terminal output for the 1.0.4 failure;
• Installer logs and /opt/api-proxy/logs/api-proxy.log;
• Table names, version numbers, and SQL errors from database migration errors.

3. Confirm the exact path: "1.0.3 installed > 1.0.3 uninstalled > 1.0.4 installation failed." If it differs, stop using this procedure and troubleshoot the actual error.

2. Back up the database and confirm rollback

1. Create a full backup of the zstack database, or a verifiable and recoverable backup appropriate for the site's database architecture.
2. Record backup time, file location, verification result, and recovery command, and confirm that the backup is not empty.
3. Ensure no other API Proxy installation, upgrade, or database migration runs concurrently during the maintenance window.
4. Have the database administrator confirm that the backup can be used for rollback before continuing.

3. Check residual objects read-only

Connect to the destination management database and run only:

SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_proxy_attachment';
SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_session';
SELECT *
FROM zstack.ovirtadapter_schema_history
WHERE version IN ('8', '9');

Confirm all conditions:

• The two ovirtadapter_snapshot_* tables are residue from the uninstalled 1.0.3 instance;
• Version 8 or 9 has failed records with success = 0;
• No active API Proxy instance still uses the tables;
• Table/database names match the site error.

If ovirtadapter_schema_history does not exist, its columns differ, version 8 or 9 succeeded, or table use is uncertain, do not delete anything; contact development.

4. Clean up uninstall residue

After backup and site change approval, the database administrator runs:

DROP TABLE IF EXISTS zstack.ovirtadapter_snapshot_proxy_attachment;
DROP TABLE IF EXISTS zstack.ovirtadapter_snapshot_session;

DELETE FROM zstack.ovirtadapter_schema_history
WHERE version IN ('8', '9')
  AND success = 0;

These statements delete only the two confirmed residual tables and explicitly failed version 8/9 migration records. Do not delete success = 1 records, expand the version range, or delete the entire ovirtadapter_schema_history table.

5. Verify cleanup

Run again:

SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_proxy_attachment';
SHOW TABLES FROM zstack LIKE 'ovirtadapter_snapshot_session';
SELECT *
FROM zstack.ovirtadapter_schema_history
WHERE version IN ('8', '9');

Confirm that both tables are absent and no version 8/9 failed record with success = 0 remains. Successful records, if any, must remain unchanged. Save before-and-after query results for audit and review.

6. Reinstall 1.0.4

1. Reinstall with the officially released API Proxy 1.0.4 package and instructions.
2. Use the correct management-node address, account, port, and certificate parameters for the original environment. Do not reuse unconfirmed temporary parameters from failed attempts.
3. Observe installation output and confirm database initialization and version migration succeed.
4. If a database error remains, stop retrying, retain the new logs, and contact development. Do not delete other tables or migration records.

7. Verify after installation

Complete at least these checks:

• API Proxy is running without repeated exits or restarts;
• Its listener matches the current installation configuration; check 16443 in the default scenario;
• /opt/api-proxy/logs/api-proxy.log has no new database migration, table-conflict, or startup-failure errors;
• Veeam can register or connect to the platform;
• Veeam can scan and list virtual machines;
• A backup of one test virtual machine succeeds;
• If recovery is used, perform a non-production-impacting recovery with a test restore point.

Rollback

Stop and roll back if cleanup objects differ from expectations, installation produces a new database error, API Proxy starts abnormally, or Veeam validation fails.

1. Stop API Proxy and any running installation or migration.
2. Save post-cleanup database state, installation output, and logs for development analysis.
3. Restore the zstack database from the verified pre-operation backup according to the site recovery process.
4. Check platform management services and database state and confirm no failed migration keeps running.
5. Have development reassess residual objects and fix scope. Do not expand DROP or DELETE scope without confirmation.

Precautions

• This SQL came from a specific site and applies only to confirmed 1.0.3 uninstall residue causing 1.0.4 installation failure.
• The chat record's SQL for the second table contained a space after the database name. This article normalizes it to the valid zstack.ovirtadapter_snapshot_session; verify against site queries before execution.
• DROP TABLE and DELETE are destructive. Back up first, verify next, execute last, and retain records.
• Do not delete successful version 8/9 records with success = 1.
• Do not execute SQL based only on a version number or installation failure; check logs, table names, and failed migration records together.
• The normal upgrade path is an in-place 1.0.4 installation; uninstalling 1.0.3 first is not recommended.
• Site chat does not preserve a final conclusion that installation and business validation fully succeeded after cleanup. Complete every listed verification after remediation.

Affected products

• Product: Veeam integration.
• Product line: ZVF.
• Component: Veeam API Proxy installer and ovirtadapter database migration.
• Version: Install API Proxy 1.0.4 after uninstalling 1.0.3.
• Trigger: Snapshot tables and failed version 8/9 migration records remain after uninstalling 1.0.3, causing database initialization or migration conflict during 1.0.4 installation.

Fix status

• Current status: Site cleanup and reinstallation procedure available; destination-environment verification required.
• Recommended upgrade: Install 1.0.4 in place if 1.0.3 remains installed.
• After uninstall: Back up the database, confirm and delete the two residual tables and failed version 8/9 records with success = 0, and reinstall 1.0.4.
• Limitations: The chat provides no general repair script or complete final validation result. Do not reuse the procedure for different versions or errors.
• Related patch/fix package: None.

Related information

• API Proxy log: /opt/api-proxy/logs/api-proxy.log.
• Key tables: zstack.ovirtadapter_snapshot_proxy_attachment, zstack.ovirtadapter_snapshot_session, and zstack.ovirtadapter_schema_history.
• Recommended images: Complete 1.0.4 error, pre-cleanup read-only results, successful reinstallation, and successful Veeam VM scan or test backup.