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

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.

Possible causes

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

• API Proxy is still initializing and early probes or the finite wait precede readiness.
• Insufficient or heavily loaded management-node resources extend Java/Spring startup.
• If service, port, or logs remain abnormal after waiting, an actual startup, configuration, port-conflict, or dependency-loading failure might exist.

Resolution

Determine whether this is normal startup

1. Inspect complete installation output, not only the first Connection refused:

• A later successful probe makes earlier failures normal startup behavior.
• If the final result remains failed, continue with service checks.

2. Wait 1 to 3 minutes after installation for Java initialization. Do not repeatedly uninstall/reinstall while it is still starting.
3. Check service status:

   systemctl status api-proxy

4. Check port 16443:

   ss -lntp | grep 16443

5. Run curl against the health-check URL in the installer documentation. A connection with expected response means API Proxy is serving requests.
6. Inspect the log:

   less /opt/api-proxy/logs/api-proxy.log

7. If initialization completes, 16443 listens, and the API test passes, ignore only the early Connection refused or timeout.

Handle slow startup

1. Check management-node CPU, memory, and disk load for shortage or obvious stalls.
2. If resources are insufficient, increase management-node resources or reduce concurrent high-load tasks, then remeasure startup time.
3. If the service started but the script exited too early, uninstall is usually unnecessary. Restart and retest:

   systemctl restart api-proxy
   systemctl status api-proxy

4. After the port listens, test API Proxy address and 16443 from the Veeam server.

Handle failure that remains after waiting

If 16443 still does not listen, treat it as actual startup failure:

1. Check exit status and failure reason:

   systemctl status api-proxy
   journalctl -u api-proxy --no-pager -n 200

2. Check for configuration parsing, port conflict, platform connection, certificate, or dependency errors:

   tail -n 300 /opt/api-proxy/logs/api-proxy.log

3. Check whether another process uses 16443:

   ss -lntp | grep 16443

4. Confirm platform address, port, context path, and installation parameters match the site.
5. If uninstall or multiple installations occurred, check for old configuration residue. Preserve evidence and contact development; do not clean the database or delete unclear configuration files directly.
6. API Proxy supports in-place installation. With a correct package and parameters, follow the documentation; uninstalling only because of the health-check message is not recommended.

Collect information

If unresolved, collect:

• ZSphere/Cloud and API Proxy versions and installer source;
• Management-node CPU/memory and incident-time load;
• Complete installation output, not only the final line;
• systemctl status api-proxy;
• journalctl -u api-proxy --no-pager -n 200;
• ss -lntp | grep 16443;
• /opt/api-proxy/logs/api-proxy.log;
• Time from installation end until the port listened;
• Health-check results from API Proxy itself and the Veeam server.

Additional information

Precautions

• Successful responses after early Connection refused indicate startup behavior, not installation failure.
• Final Health check failed alone also does not prove failure; wait and inspect service, port, API response, and logs.
• Treat it as actual failure only when the service remains unavailable after a reasonable wait or logs show an explicit exception.
• Do not repeatedly uninstall API Proxy after one health-check failure; old uninstall versions might leave residue and complicate diagnosis.
• 16443 is the external API Proxy port, not necessarily the backend platform API port.
• Untrusted certificates, API Proxy platform-connection timeout, and data-agent health failure are separate issues.

Fix status

• Current status: Assessment and workaround available.
• Functional state: No functional fix is needed when a later probe succeeds or the service listens later.
• Product improvement: ZSV-12324 tracks misleading health-check messaging.
• Fixed version: None specified.
• Related patch/fix package: None.

Related information

• Related Jira: ZSV-12324.
• API Proxy log: /opt/api-proxy/logs/api-proxy.log.
• API Proxy service port: 16443, subject to actual installation configuration.
• Recommended images: Complete output showing the first 2 Connection refused probes and later success, plus validation showing 16443 listening after Health check failed on a low-specification management node.