Issue/Introduction

Source and classification

• Source: Veeam integration support cases and internal reproduction.
• Classification: VM metadata configuration; some older API Proxy batch-backup scenarios might also have a compatibility issue.
• Confirmation basis: When the platform OS type was only generic Windows, Veeam did not recognize new restore points for Windows file-level restore. Selecting the actual version, such as Windows Server 2019, and creating a new backup enabled it.
• Internal tracking: No related Jira.

Issue metadata

• Issue ID: None.
• Component/product: ZSphere, Cloud, Veeam API Proxy, and Veeam Backup & Replication.
• Status: Main scenario has a resolution.
• Priority/severity: General.
• Confirmed environment: Cloud 5.4.8, Veeam 12, and API Proxy 1.0.x; check the same OS-type metadata for ZSphere integration.
• First fixed version: OS metadata needs no code fix. A later 1.0.3 followed up the older batch-backup compatibility issue; use its release notes for support scope.
• Confirmation date: July 6, 2026.
• Last updated: September 1, 2026.

Problem description

After backing up a Windows VM on ZSphere or Cloud, Veeam might disable file-level restore for its restore point even though the source actually runs Windows.

The main confirmed cause is a generic Windows OS type, or missing/inaccurate version metadata after migration. Veeam uses platform metadata to classify the guest when creating the restore point. Backup can succeed while file-level restore remains unavailable.

Changing platform OS type affects only future restore points. Existing guest-classification data does not update, so create a new backup after correction.

An older API Proxy with Veeam 12 also showed a multi-VM batch-backup compatibility issue. If OS type is correct, inspect version and backup mode.

Symptoms

• Windows VM backup succeeds, but file-level restore is disabled.
• Multiple Windows VMs from one batch cannot use it.
• Veeam does not classify the restore point as Windows or offers only whole-VM/disk recovery.
• The source runs Windows, but the platform says only Windows rather than Windows Server 2019, for example.
• Migrated VMs more often retain generic, absent, or inaccurate types.
• After selecting the actual Windows version and backing up again, a new restore point enables file-level restore.

Site screenshot

Impact

• Individual files/folders cannot be restored through Veeam.
• Whole-VM, disk, or other recovery might be required, increasing time and impact.
• A disabled action does not mean backup failure or damaged data.
• Changing the VM operating system type does not repair existing restore points; a new backup is required for verification.
• Guest network/credentials can affect later writeback but are a different stage from action enablement.

Environment

• Products: ZSphere, ZStack Cloud, and Veeam Backup & Replication.
• Product line: ZVF and Cloud-related Veeam integration.
• Components: VM OS metadata, Veeam API Proxy, and Veeam file-level restore.
• Confirmed environment: Cloud 5.4.8, Veeam 12, API Proxy 1.0.x.
• Trigger: Generic, missing, or inaccurate Windows OS type; some older API Proxy multi-VM batch scenarios might also trigger it.

Possible causes

This symptom can be caused by one or more of the following conditions:

• Platform Windows type is generic, missing, or inconsistent with the VM.
• Validation uses an old restore point after the operating system metadata changes, although the guest-classification information in the old restore point is not updated.
• With correct OS type, an older API Proxy multi-VM batch compatibility issue might disable the action.

Resolution

Confirm the scope

1. Record the following version and scenario information:

• ZSphere or Cloud version.
• API Proxy version.
• Full Veeam version; do not record only major version 12 or 13.
• Whether this is a single-VM backup or a multi-VM batch backup.
• Whether the current restore point was created before the configuration change or is a new restore point created afterward.

2. Confirm backup succeeded; handle backup failure first.
3. In Veeam, open the target restore point and confirm that only file-level restore is disabled, not every recovery action.

Check and correct VM operating system type

1. Log in to the ZSphere or Cloud management UI and open the affected Windows VM details or edit page.
2. Correct generic Windows, blank, or inaccurate type.
3. Select the actual version, such as Windows Server 2019.
4. Do not select an inaccurate version merely to enable the action; confirm the guest from the VM or asset data.
5. Save and run a new Veeam backup.
6. Open the new restore point, confirm file-level restore is enabled, and verify browsing files/folders.

When the OS type is correct but the action remains disabled

1. Confirm API Proxy version. Older versions with Veeam 12 multi-VM batch backup might be incompatible.
2. Upgrade according to release notes to a formally released version containing the relevant fix. The group followed up with 1.0.3; prefer the current formal release.
3. Save installation parameters and logs before an in-place API Proxy upgrade. Uninstalling first is not recommended solely for upgrade.
4. Create or run a new backup after the upgrade and validate the new restore point. Do not determine whether the fix works by using only an old restore point created before the upgrade.
5. Compare a single-VM backup:

• If single-VM works but batch does not, prioritize batch compatibility.
• If neither works, continue with OS recognition, Veeam version, and VM metadata.

When file-level restore is enabled but execution fails

If the action is enabled but browsing files, mounting the backup, or writing files back to the guest fails, troubleshoot the Veeam file-level restore execution stage, focusing on:

• Network connectivity from the Veeam server or Mount Server to the target Windows VM.
• Windows guest credentials and local or domain authentication.
• Services, shares, and firewall policies required by Veeam.
• The exact mount or writeback error in the Veeam task log.

These failures are not the disabled-action issue covered by this article.

Collect information if unresolved

Collect the following information and contact engineering or Technical Support:

• ZSphere or Cloud version, API Proxy version, and full Veeam version.
• Affected VM UUID, actual operating system, and operating system type configured on the platform.
• Whether the VM was migrated from another platform.
• Comparison result between single-VM and batch backups.
• Restore-point creation times before and after correcting the operating system type.
• Complete screenshot of the disabled action in Veeam.
• Veeam backup task log.
• Corresponding backup-task entries in /opt/api-proxy/logs/api-proxy.log.

Additional information

Precautions

• Validate only with a new restore point after OS-type correction.
• OS type must match the guest; do not enter a false version to bypass UI restrictions.
• Disabled Windows file-level restore and L3 NIC occupation during whole-VM recovery are separate. The latter in Cloud/API Proxy 1.0.3 was fixed by 1.0.4.
• Network, credential, or Mount Server errors after enablement follow the native Veeam workflow.
• Check VMware GuestTools residue for Windows VMs migrated/recovered to ZSphere/Cloud, but it is not a confirmed direct cause here.

Fix status

• Current status: Main scenario has a resolution.
• Configuration: Set the actual specific Windows version and create a new restore point.
• Plugin: Upgrade older batch-backup compatibility issues to a formal fixed release; 1.0.3 was followed up in the group, subject to release notes.
• Limitation: Metadata changes and API Proxy upgrades do not rewrite existing restore-point classification.

Related information

• API Proxy log: /opt/api-proxy/logs/api-proxy.log.
• Related version: API Proxy 1.0.3 followed up Veeam 12 batch-backup file-level restore.
• Separate issue: Cloud/API Proxy 1.0.3 L3 NIC occupation during whole-VM restore was fixed in 1.0.4.
• Recommended images: The disabled Veeam file-level restore action, the generic platform Windows type, the corrected specific Windows type, and the enabled action on a new restore point.