Issue/Introduction

This article troubleshoots subsequent backups being incorrectly rejected for insufficient capacity after Vinchin finishes a backup and deletes a VM snapshot: the page shows Snapshot Capacity as 0 B, but QueryPrimaryStorage.availableCapacity remains lower than before the backup.

Symptoms

• ZSphere 5.0.3 uses Vinchin backup with SharedBlock/SAN data storage.
• Available capacity decreases during backup. After Vinchin deletes the snapshot, the UI shows Snapshot Capacity as 0 B.
• CLI availableCapacity does not return to its pre-backup value, and Capacity Percent Used remains high.
• In the recorded case, saving a changed Overcommit Ratio and then changing it back triggered capacity recalculation and recovery. This briefly changes the allocation calculation and is only a controlled workaround, not a root-cause conclusion.

Environment

• Product: ZVF ZSphere
• Version: 5.0.3
• Components: ZSphere SharedBlock/SAN data storage, capacity accounting, and the Vinchin snapshot process
• Deployment: Vinchin backup creates a VM snapshot and deletes it when the backup ends

Possible causes

• The post-deletion capacity update and PrimaryStorageCapacityVO recalculation are not synchronized promptly.
• The UI display value and CLI availableCapacity are read at different times.
• Current evidence proves only that triggering recalculation restores the value; it does not identify where the capacity update was lost.

Resolution

1. Record four capacity sets over one complete backup cycle

• Check: The destination data storage and snapshot created/deleted by the same Vinchin backup.
• Location: Before backup, after snapshot creation, after Vinchin reports successful deletion, and after manual refresh, run QueryPrimaryStorage uuid=PRIMARY_STORAGE_UUID. Record availableCapacity, availablePhysicalCapacity, and totalCapacity; also save UI Snapshot Capacity, Free to Allocate, and Capacity Percent Used.
• Expected result: After snapshot deletion completes, backend and UI capacity values both return to levels consistent with actual allocation.
• Exception handling: If only the UI returns to 0 B while availableCapacity remains below its pre-backup value, continue by confirming that the snapshot and background task actually ended.

2. Exclude an actual residual snapshot or incomplete deletion task

• Check: VM Snapshot/VolumeSnapshot lists, Vinchin deletion result, and ZSphere task state.
• Location: Query by VM UUID, snapshot UUID, and backup time, and use this log chain to confirm completion:

1. From ZSphere task details, record the snapshot-deletion task apiId, VM UUID, snapshot UUID, and exact time. Then run on the management node:

     KB_API_UUID='<apiId-from-task-details>'
     cd /usr/local/zstack/apache-tomcat/logs || exit 1
     ls -lh management-server.log*
     zgrep -a -n -C 3 "$KB_API_UUID" management-server.log*
     zgrep -a -n "$KB_API_UUID" management-server.log* | grep -iE 'json POST|http response|snapshot|delete|capacity'

Record the destination ZSphere host, URI, taskuuid/taskUuid, and response. If Vinchin provides only a snapshot UUID, first search management-server.log* by that UUID and exact time, and obtain apiUuid and taskuuid from the matching line.

2. On the ZSphere host addressed by the request, query current and archived KVM Agent logs by taskuuid:

     KB_TASK_UUID='<taskuuid-from-management-server-log>'
     cd /var/log/zstack || exit 1
     ls -lh zstack-kvmagent.log*
     zgrep -a -n -C 5 "$KB_TASK_UUID" zstack-kvmagent.log*
     zgrep -a -n "$KB_TASK_UUID" zstack-kvmagent.log* | grep -iE 'snapshot|delete|merge|capacity|error|fail|timeout'

3. Enter the capacity-not-recalculated branch only if the management-node response, KVM Agent completion log, Vinchin result, and object query all show deletion completed. If any side is Running, timed out, or still merging, continue observing the original task and do not trigger the workaround. To inspect current logs, use vim -R LOG_FILE, enter /, paste the UUID, press Enter, use n for the next match, and enter :q! to quit.

• Expected result: Vinchin and ZSphere both confirm deletion, UI Snapshot Capacity is 0 B, and no other task continues consuming capacity.
• Exception handling: If a residual object or background task exists, handle its deletion process first. Do not classify low capacity as a missed recalculation in this case.

3. Prefer the supported capacity synchronization API

• Check: Destination data-storage UUID and capacity responses before and after synchronization.
• Location: The code provides the SyncPrimaryStorageCapacity API. When no snapshot creation/deletion task is running, an authorized administrator runs:

  SyncPrimaryStorageCapacity primaryStorageUuid=PRIMARY_STORAGE_UUID

• Expected result: The API succeeds, after which QueryPrimaryStorage and the UI show consistent available capacity.
• Exception handling: If the API fails or capacity remains unchanged, save the request/response and before-and-after values. Do not modify the database; proceed to the controlled workaround.

4. If necessary, use the controlled Overcommit Ratio workaround

Workaround

• Support-assisted method: Use only when the original Overcommit Ratio is confirmed as 1:1, the snapshot is deleted, no capacity allocation is in progress, and SyncPrimaryStorageCapacity did not restore capacity. Record the original value and capacity snapshot. During a maintenance window, change the destination Data Storage Overcommit Ratio from 1:1 to 1.2:1 and save. After recalculation completes, immediately change it back to 1:1 and save again.
• Expected result: After restoring the original value, availableCapacity, Free to Allocate, and Capacity Percent Used match actual usage. After one subsequent small backup creates and deletes a snapshot, capacity automatically returns.
• Exception handling: Start no backup or allocation task while changing the value. If capacity does not recover, the original value cannot be restored, or a new allocation begins, stop immediately and contact ZStack Technical Support. This workaround proves only that recalculation can restore the value; it does not prove the root cause, and 1.2:1 must not remain permanently configured.

Additional information

• Support information must include the exact time window, resource and task UUIDs, complete error text, and relevant component logs.
• Do not extrapolate one site result to all versions. If the root cause remains open or an operation might affect services or data, stop self-service handling and submit the evidence listed in this article.