Knowledge Base›Troubleshooting›Health check fails during Veeam API Proxy installation, but the service starts later

Health check fails during Veeam API Proxy installation, but the service starts later

TroubleshootingZVF · Veeam API ProxyVersions1.0.xArticle IDKB-100571Updated2026-09-16

Issue/Introduction

Source and classification

Source: Site case from the Veeam integration Technical Support group.
Classification: Service-startup timing and health-check messaging during installation.
Confirmation basis: The first 2 installation probes reported Connection refused, the third succeeded, and API Proxy started normally. On another low-specification management node, initialization exceeded the script's approximately 30-second wait and reported health-check failure, but the service later listened on 16443.
Internal tracking: ZSV-12324.

Issue metadata

Issue ID: ZSV-12324.
Component/product: ZSphere, Cloud, and Veeam API Proxy.
Status: Service function is usually normal; interpret installation errors with the final probe result.
Priority/severity: General.
Confirmed version: API Proxy 1.0.x.
First fixed version: None specified; ZSV-12324 tracks messaging improvement.
Confirmation date: May 29, 2026.
Last updated: September 2, 2026.

Problem description

During installation, the script probes the API immediately after starting the service. Java initialization takes time, so early connections might report Connection refused. If a later probe succeeds, the service started normally and the earlier failures were transient startup behavior.

The installer waits a limited time for API Proxy to listen on 16443. On a management node with slow CPU, memory, or disk, Spring initialization might exceed this wait and the installer reports Health check failed, while the process continues starting and later listens normally.

Do not conclude installation failure from one Connection refused or Health check failed. Check the final probe, service state, listener, API test, and application log together.

Symptoms

Installation repeatedly shows:

  Connection refused

The first 2 API probes fail, the third succeeds, and API Proxy works afterward.
The installer shows:

  Health check failed

Port 16443 is not listening when installation ends but starts later.
/opt/api-proxy/logs/api-proxy.log shows Java/Spring initialization without an explicit startup exception.
Low-specification or busy management nodes more often exceed the wait.

Site screenshot

Figure 1. API Proxy installer health check failure

Note:

In a similar site case, the installer reported Health check failed after 30 waits. Interpret it with service state, port listener, and application logs; it alone does not prove final startup failure.

Impact

Operators might misclassify installation as failed and repeatedly install or uninstall.
If the service eventually starts, earlier probe failures do not affect Veeam integration, backup, or recovery.
If it remains unavailable after waiting, treat it as actual startup failure and continue troubleshooting; do not ignore it under this article.
No evidence indicates that transient health-check failure damages VMs, backup data, or platform data.

Environment

Products: ZSphere and ZStack Cloud.
Product line: ZVF and Cloud-related Veeam integration scenarios.
Components: Veeam API Proxy installer and service.
Confirmed version: API Proxy 1.0.x.
Trigger: Service initialization is incomplete, or management-node performance makes startup exceed the installer wait.