Troubleshoot "Connection to XXXX refused" error in OSS Java SDK - Object Storage Service

When using the OSS Java SDK, you may see an error like this:

Connection to http://buname.oss-cn-hangzhou-internal.aliyuncs.com refused
[RequestId]: Unknown
        at com.aliyun.oss.common.utils.ExceptionFactory.createNetworkException(ExceptionFactory.java:31)
        at com.aliyun.oss.common.comm.DefaultServiceClient.sendRequestCore(DefaultServiceClient.java:57)
        at com.aliyun.oss.common.comm.ServiceClient.sendRequestImpl(ServiceClient.java:191)
        at com.aliyun.oss.common.comm.ServiceClient.sendRequest(ServiceClient.java:151)
        at com.aliyun.oss.internal.OSSOperation.send(OSSOperation.java:71)
        at com.aliyun.oss.internal.OSSObjectOperation.putObject(OSSObjectOperation.java:92)
        at com.aliyun.oss.OSSClient.putObject(OSSClient.java:394)
        at osscs1.OSSPutObjectSample.uploadFile(OSSPutObjectSample.java:82)
        at osscs1.OSSPutObjectSample.main(OSSPutObjectSample.java:46)

Causes

This error has two common causes. Check which applies to your environment before proceeding.

Cause 1: Using an internal endpoint from outside the internal network

Internal endpoints contain -internal in the URL (for example, oss-cn-hangzhou-internal.aliyuncs.com). These endpoints are only accessible from clients in the internal network of the same region as your OSS bucket. If your client is not in the internal network of the same region, the connection will be refused.

How to identify this cause: Check whether the endpoint in your SDK configuration contains -internal. If it does, and your client is not in the internal network of the same region as the OSS bucket, this is the cause.

Cause 2: Port 80 or 443 is blocked

Even when the client and OSS are in the same region, network policies — such as firewall rules or security group settings — may block port 80 or 443, preventing the SDK from reaching OSS.

How to identify this cause: Use telnet to test the port, as described in the following section.

Diagnose the issue

Run the following commands on the client machine to identify the cause.

Step 1: Test basic connectivity with ping

ping oss-cn-hangzhou.aliyuncs.com

If the command returns replies similar to the following, basic network connectivity and DNS resolution are working:

PING oss-cn-hangzhou.aliyuncs.com (x.x.x.x): 56 data bytes
64 bytes from x.x.x.x: icmp_seq=0 ttl=xx time=x.xxx ms

If the command times out or returns an error, your machine cannot reach the OSS public endpoint. Verify your network configuration or contact your network administrator.

Step 2: Test port availability with telnet

telnet oss-cn-hangzhou.aliyuncs.com 80

If port 80 is open, you will see a blank screen or a Connected message similar to:

Trying x.x.x.x...
Connected to oss-cn-hangzhou.aliyuncs.com.

If you see Connection refused or the command times out, port 80 is blocked on your network. Test port 443 as well:

telnet oss-cn-hangzhou.aliyuncs.com 443

Note: Replace oss-cn-hangzhou.aliyuncs.com with the public endpoint for your region. For the full list of endpoints, see Access domain name and data center.

Solution

Switch to the public endpoint and update your SDK configuration:

private static final String OSS_ENDPOINT = "http://oss-cn-hangzhou.aliyuncs.com/";
OSSClient client = new OSSClient(OSS_ENDPOINT, ACCESS_ID, ACCESS_KEY);

If telnet confirms that port 80 and 443 are both blocked, work with your network administrator to open the required ports before switching the endpoint.

What's next

Access domain name and data center — find the public endpoint for your region