How do I troubleshoot a ZCenter startup or API failure caused by a database connection issue?

Issue/Introduction

This article describes how to troubleshoot database issues when Gateway remains accessible but Base, Portal, or a business service cannot start, an API fails, or intermittent timeouts occur. It focuses on database availability, authentication, connection pools, read-only state, and disk capacity. Use a separate KB to troubleshoot Flyway script validation issues.

Symptoms

• A service startup log contains Unable to obtain connection, Communications link failure, or Application run failed.
• An API returns an application failure, and the log contains HikariPool or Connection is not available, request timed out.
• The database returns Access denied for user, Unknown database, Too many connections, or a read-only error.
• The Gateway port is available, but the target service is not registered, returns 503, or fails to provide a business response.
• Database disk space or inodes are exhausted, or an InnoDB write fails.

Environment

• Product: ZCenter
• Version: 5.1.0
• Component: MariaDB/MySQL, HikariCP, Base, Portal, and business services

Possible causes

• The database process is not running, port 3306 is unreachable, or a firewall or route is abnormal.