First-time connection failures between a Kafka client and an ApsaraMQ for Kafka instance typically fall into one of three categories: network connectivity, client version mismatch, or incorrect configuration. Work through the checks below in order -- most issues resolve in the first two sections.
Check network connectivity
Network issues are the most common cause of first-time connection failures. Start by identifying which network scenario applies to your deployment, then verify connectivity.
Client and instance are in the same VPC
If your client runs on an Elastic Compute Service (ECS) instance in the same Virtual Private Cloud (VPC) as the ApsaraMQ for Kafka instance, verify that the client can reach the broker endpoint listed on the instance details page in the ApsaraMQ for Kafka console.
Client and instance are in different VPCs
An ApsaraMQ for Kafka VPC-connected instance is reachable only from within the same VPC. If your ECS instance is in a different VPC, the connection fails.
Fix: Deploy the client on an ECS instance that resides in the same VPC as the ApsaraMQ for Kafka instance. For setup instructions, see Purchase and deploy a VPC-connected instance.
Client connects over the Internet to a VPC-connected instance
A VPC-connected instance does not expose a public endpoint. Attempting to reach it over the Internet fails because VPC-connected instances accept traffic only from within the VPC.
Fix: Either deploy the client inside the same VPC, or use an Internet-enabled ApsaraMQ for Kafka instance that provides a public endpoint.
Client IP address is not in the whitelist
Even when the client is in the correct VPC, ApsaraMQ for Kafka blocks connections from IP addresses that are not in the instance whitelist.
Fix: Add the client IP address to the whitelist. For instructions, see Configure whitelists.
Check the client version
A version mismatch between the Kafka client library and the ApsaraMQ for Kafka broker can cause connection errors or unexpected behavior.
Match the client library version to the broker version shown on the instance details page in the ApsaraMQ for Kafka console. The broker version takes priority -- always align the client to it, not the other way around.
For example, if the instance runs broker version 0.10.2.2, use a Kafka client library of the same version.
For working client code samples in multiple languages, see aliware-kafka-demos.
Check endpoint and permission configuration
If network connectivity and client version are both correct, the issue is likely in the client configuration.
Invalid or wrong endpoint
Make sure the endpoint address in the client configuration matches the default endpoint shown on the instance details page. Common mistakes include:
Copying the endpoint for the wrong access method (VPC vs. Internet).
Copying the endpoint from a different instance.
If the instance has both public and VPC endpoints, each access method has a separate endpoint string. Using the wrong one causes the connection to fail.
Missing RAM permissions
If the Alibaba Cloud account used by the client is a Resource Access Management (RAM) user, verify that the RAM user has the required permissions to access ApsaraMQ for Kafka resources. The broker rejects connection attempts from accounts with insufficient permissions.
For the complete setup checklist -- including endpoint configuration and RAM permissions -- see Getting started overview.
Contact support
If the issue persists after all three checks above, collect the following information and contact Alibaba Cloud support:
Full exception message and stack trace from the client
ApsaraMQ for Kafka instance ID and broker version
Network environment (VPC ID, ECS instance ID, region)
Client library language and version