Alibaba Cloud SDK:FAQ

• Ensure that the Java environment is installed correctly. Your Java version must be 1.8 or later.

• Ensure that your network can access Alibaba Cloud APIs.

• AK parameter passing issues.

• unable to get credentials from any of the providers in the chain: ...

• code 403, You are not authorized to do this operation. Action: xxxx

• Error when importing Maven dependencies: Could not find artifact com.aliyun:XX:XX

• java: Error: release version X not supported.

• java: Compilation failed: internal java compiler error.

• Code 400: A parameter is required for this action.

• java.lang.NoSuchMethodError, java.lang.NoSuchFieldError

• "TeaUnretryableException: timeout", "java.net.SocketTimeoutException: connect timed out", "java.net.SocketTimeoutException: Read timed out", "SDK.ServerUnreachable", "Connection aborted", or "RemoteDisconnected".

• Your request is denied as lack of SSL protection. RequestId.

• code: 404, Specified API is not found. Please check your URL and method.

• Unexpected response code for CONNECT: 400.

• Can not set java.lang.String field com.aliyun.imm20200930.models.GenerateWebofficeTokenShrinkRequest.userShrink to java.util.

• Failed to automatically download dependencies with Maven in IDEA.

• How to avoid WARNING messages caused by reflection.

• Specified signature does not match our calculation.

• SDK.EndpointResolvingError: "No such region 'cn-XX'. Please check your region ID".

• Failed to instantiate [com.aliyuncs.IAcsClient]: Factory method 'iAcsClient' threw exception with message: org/apache/http/conn/ssl/DefaultHostnameVerifier.

• Error when calling an OpenAPI: code: 401, You have not activated the XXX service, or a similar message.

• Failed to get RAM session credentials from ECS metadata service. HttpCode=XX

• There is a risk of leakage of this AccessKey

• Request was denied due to API flow control

• Specified access key denied due to access policy

• com.aliyuncs.exceptions.ClientException: SDK.InvalidRegionId: Can not find endpoint to access

AK parameter passing issues.

Symptom: An error occurs when the code runs. If the error message contains the following information, the AccessKey was not set correctly.

• V2.0 SDK: Cannot invoke "com.aliyun.credentials.Client.getCredential()" because "this._credential" is null.

• V1.0 SDK: ErrCode: MissingAccessKeyId. ErrMsg: AccessKeyId is mandatory for this action.

Solution:

1. Run the following command to check if ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET are configured in your environment variables:

   Linux/macOS

   echo $ALIBABA_CLOUD_ACCESS_KEY_ID
   echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

   Windows

   echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
   echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

   If the correct AccessKey is returned, the configuration is successful. If the return value is empty or incorrect, try to set it again. For more information, see Configure environment variables on Linux, macOS, and Windows systems.

2. Check your code for errors related to the AK.

   Common incorrect example:

   Config config = new Config()
            .setAccessKeyId(System.getenv("yourAccessKeyID"))   
            .setAccessKeySecret(System.getenv("yourSecret")); 

   Correct example:

   Config config = new Config()
           .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
           .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

   Note

   System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID") and System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET") retrieve the values of ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET from the environment variables.

   Important

   Do not hardcode your AccessKey in online code. This practice poses a security risk.

unable to get credentials from any of the providers in the chain : ...

Cause: You used the default credential in your project (as shown in the code example below), but this error occurred because you did not configure any of the credential types supported by the default credential.

com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
        .setCredential(credential);

Solution:

• If you want to use an AccessKey directly in your code, see the following code:

  com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
          // This example shows how to get the AccessKey ID from an environment variable.
          .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
          // This example shows how to get the AccessKey secret from an environment variable.
          .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

  To use other credentials, see Manage access credentials.

• To continue using the default credential, you must configure any of the credential types supported by the default credential provider chain.

code 403, You are not authorized to do this operation. Action: xxxx.

The direct cause of this issue is that the Resource Access Management (RAM) user, role, or user group calling the API has not been granted the required permissions to perform the API operation. The Action:XXXX in the error message indicates the specific API operation you are trying to call. For example, Action:dysms:SendSms indicates that you need to call the SendSms API of Short Message Service, but the current account does not have permission to call this API. Therefore, you need to grant the RAM account permission to send text messages.

Solution:

1. Contact a RAM user with administrator permissions and create a custom permission policy based on the following policy document. For more information, see Create a custom permission policy.

   Note

   This access policy only allows calls to the SendSms API of Short Message Service (dysms). Replace it with the actual service and API from your error message.

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": "dysms:SendSms",
         "Resource": "*"
       }
     ]
   }

2. Grant permissions to the RAM account. For more information, see:

   • Manage RAM user permissions.

   • Manage RAM role permissions.

   • Grant permissions to a RAM user group.

Error when importing Maven dependencies: Could not find artifact com.aliyun:XX:XX

Description:

When importing dependencies in a Maven project, an error message indicates that the corresponding dependency cannot be found.

Solution:

Configure the Maven central repository address in your project. This tells Maven where to download dependencies from during the project build. You can use one of the following methods:

• Add the following content to the pom.xml file:

  <repositories>
      <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
      </repository>
      <repository>
          <id>nexus-noke</id>
          <url>http://nexus.noke.com/nexus/content/groups/public/</url>
      </repository>
  </repositories>

• Add the following content to the settings.xml file:

  <settings>
      <!-- Existing settings -->
      
      <mirrors>
          <mirror>
              <!-- This id can be any unique identifier -->
              <id>central</id>
              <mirrorOf>central</mirrorOf>
              <name>Maven Central Mirror</name>
              <url>https://repo1.maven.org/maven2</url>
          </mirror>
      </mirrors>
  </settings>

java: Error: release version X not supported.

In IntelliJ IDEA, press Ctrl+Alt+Shift+S to open the Project Structure window. Select Modules. On the right, for Language Level, select the version that matches your JDK version. For example, if you are using JDK 8, select "8 - Lambdas, type annotations etc." for Language Level. Click Apply, then click OK.

java: Compilation failed: internal java compiler error.

In the IntelliJ IDEA menu bar, click File → Settings → Build, Execution, Deployment → Compiler → Java Compiler. For Project bytecode version and Target bytecode version, select the version that matches your JDK version. For example, if you are using JDK 8, select 8 for both options. Click Apply, then click OK.

code: 400, <CERTAIN_FIELD > is mandatory for this action.

The direct cause of this issue is that a required parameter was not filled in when calling the API. Solution:

The following example uses the SendSms API of Short Message Service:

• Go to the API debugging page in the OpenAPI Portal, and select the cloud product and API.

• Carefully compare the constructed request object, such as SendSmsRequest, to ensure all required fields, such as the phone number and signature, are filled.

• Refer to the API documentation to confirm the required parameters.

• Ensure the values of the required parameters are correct. For example, check if the phone number format meets the requirements.

• Before calling the API, the SDK automatically validates the parameters. If a required parameter is missing, you receive an error like MissingRequiredParameter. For example, if the phone number parameter is missing, the error "MissingPhoneNumbers: code: 400" is reported.

SendSmsRequest sendSmsRequest = new SendSmsRequest()
        // Replace with the phone number that will receive the text message.
        .setPhoneNumbers("<YOUR_VALUE>")
        // Replace with your SMS signature.
        .setSignName("<YOUR_VALUE>")
        // Replace with your SMS template code.
        .setTemplateCode("<YOUR_VALUE>");

java.lang.NoSuchMethodError, java.lang.NoSuchFieldError

Cause:

This type of exception usually occurs when the Java runtime environment tries to call a method or access a field that does not exist. Possible causes include the following:

• Outdated dependency version: An outdated dependency version may be specified in the configuration file of a build tool such as Maven or Gradle (for example, pom.xml or build.gradle).

• Dependency conflict: Multiple versions of the same dependency may exist in the project, causing a lower version of the dependency to be loaded at runtime.

• Dependencies not updated: After updating a dependency version, the project was not rebuilt or the cache was not cleared, causing the old version to still be in use.

• Inconsistent compile-time and runtime environments: The dependency version used at compile-time is inconsistent with the dependency version at runtime.

• Classpath conflict: The wrong classpath was selected during import.

Solution:

1. Check the example provided in the Alibaba Cloud OpenAPI Portal to see if there is an error in the classpath.

2. If the classpath is correct, you can obtain the specific class that caused the error from the exception stack information and find the corresponding dependency and version.

3. Run the following command to view the direct and transitive dependencies of the project, along with specific conflicts and duplicates.

   • Maven: Maven uses the "shortest path first" and "declaration order first" strategies by default to determine which dependency version to use. You can resolve conflicts by adjusting the order of dependencies.

     mvn dependency:tree -Dverbose

   • Gradle: Gradle uses the "highest version first" strategy by default to resolve conflicts. This means only outdated versions can be an issue. Skip to step 4 to obtain the latest version of the dependency.

4. In the output dependency tree, check if there is a conflict with the dependency or its parent dependency. If there is a conflict, move the highest version of the dependency or its parent dependency to the top of the <dependencies></dependencies> section in the pom.xml file. Run mvn clean install -U to rebuild. If the error persists, continue with the following steps.

5. Find the latest version of the corresponding dependency in V2.0 Java SDK common dependency packages. Respecify the latest version of the dependency in the configuration file of the build tool, such as Maven or Gradle (for example, pom.xml or build.gradle).

6. Run the following command to clean and rebuild the project:

   • Maven

     mvn clean install -U

   • Gradle:

     gradle clean build --refresh-dependencies

7. Verify that the issue is resolved.

Example:

The exception message is java.lang.NoSuchMethodError: com.aliyun.credentials.Client.getCredential().

1. After checking, the classpath is correct.

2. According to the exception message, the exception occurred in the com.aliyun.credentials.Client class, which is in the credentials-java dependency. The currently referenced version is 0.2.4.

3. After running mvn dependency:tree -Dverbose, it is found that the parent dependency credentials-java, tea-openapi, has a version conflict. The currently referenced version is 0.3.2, and the conflicting version is 0.3.8. We recommend moving the parent dependency corresponding to version tea-openapi 0.3.8 to the top of the <dependencies></dependencies> section.

4. Run the mvn clean install -U command to clean and rebuild the project, and verify that the issue is resolved.

5. If the issue persists, you can obtain the latest version of credentials-java from Maven Central: com.aliyun:credentials-java and manually add the dependency to the pom.xml file.

"TeaUnretryableException: timeout", "java.net.SocketTimeoutException: connect timed out", "java.net.SocketTimeoutException: Read timed out", "SDK.ServerUnreachable", "Connection aborted", or "RemoteDisconnected".

Timeout issues can be caused by several factors. The following are common causes and their solutions:

// Runtime parameter timeout setting. This is effective only for requests that use this runtime parameter instance.
RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.connectTimeout = 5000;

// Runtime parameter timeout setting. This is effective only for requests that use this runtime parameter instance.
RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.readTimeout = 10000;

Your request is denied as lack of ssl protect.RequestId .

This issue occurs because the API requires you to use the HTTPS protocol, but you used the HTTP protocol.

Solution:

• For the V1.0 SDK, you can set the request to be sent over the HTTPS protocol on the Request object:

  request.setSysProtocol(com.aliyuncs.http.ProtocolType.HTTPS);

• Use the V2.0 SDK. The V2.0 SDK uses the HTTPS protocol by default.

code: 404, Specified api is not found, please check your url and method.

The direct cause of this error may be that you entered an incorrect Endpoint or RegionId when calling a product API. The solution is as follows:

Ensure the region you selected supports the service you are calling. You can find the product's Endpoint on its homepage in the OpenAPI Developer Portal. The following example uses Short Message Service.

Unexpected response code for CONNECT: 400.

The direct cause of this issue is that the request was intercepted by an intermediate node and did not reach the Alibaba Cloud gateway.

Solution:

• The proxy server configuration may be incorrect. This means the proxy service cannot correctly forward the request to the Alibaba Cloud gateway. You can check the proxy configuration with curl. curl https://<Alibaba Cloud service domain name>/ -v -x <proxy IP address/proxy domain name>:<proxy port>, for example, curl https://ecs-cn-hangzhou.aliyuncs.com/ -v -x 127.0.0.1:3128.

• The request may be blocked by an internal network firewall. In a local environment, try switching the network environment, for example, by connecting to a mobile hotspot.

Can not set java.lang.String field com.aliyun.imm20200930.models.GenerateWebofficeTokenShrinkRequest.userShrink to java.util .

The direct cause of this issue is that an older version of the Tea package cannot convert a complex structure into a String structure, which causes an error.

Solution:

Upgrade the Tea package to version 1.2.7 or later.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>tea</artifactId>
  <version>1.2.7</version>
</dependency>

Failed to automatically download dependencies with Maven in IDEA.

• Update the Maven repository

  Open the "File" menu and select "Settings" (or "Preferences"). In the navigation pane on the left, expand "Build, Execution, Deployment", and then select "Build Tools" > "Maven". Find the "Repositories" tab, select the local repository, click the "Update" button, and wait for the update to complete.

• Check the IDEA cache

  Open the "File" menu, select "Invalidate Caches...". In the dialog box that appears, select "Invalidate and Restart", and wait for IDEA to clear the cache and restart.

  

• Check the network connection

  If Maven cannot connect to the central repository or other remote repositories, it may not be able to download dependencies. Ensure your network connection is normal and that no firewalls or proxy servers are blocking Maven's access.

• Check the Maven configuration

  Check that the Maven configuration file (usually settings.xml) is configured correctly. Ensure "localRepository" points to the correct local repository path, and that "mirrors", "proxies", and "profiles" are configured correctly.

How to avoid WARNING messages caused by reflection.

When you use the Alibaba Cloud SDK with a higher version of the JDK for development, you may encounter warning messages related to reflection. These warnings can affect the program output, especially when you want to avoid unnecessary log messages in a production environment.

Solution:

You can set the ALIBABA_CLOUD_SDK_LOG_LEVEL environment variable to ERROR to suppress the display of warning messages. Procedure:

1. Set the environment variable:

   Windows

   set ALIBABA_CLOUD_SDK_LOG_LEVEL=ERROR

   Linux/macOS

   export ALIBABA_CLOUD_SDK_LOG_LEVEL=ERROR

2. Confirm the environment variable setting:

   Windows

   echo %ALIBABA_CLOUD_SDK_LOG_LEVEL%

   Linux/macOS

   echo $ALIBABA_CLOUD_SDK_LOG_LEVEL

3. Start your application: After you configure the environment variable, start your Java application. At this point, the warning messages generated by the Alibaba Cloud SDK will not be displayed. You will only see log messages of the ERROR level or higher.

Specified signature does not match our calculation.

The direct cause of this issue is usually a mismatch between the signature of the request and the signature calculated by the server. Possible causes include but are not limited to:

• AccessKey (AK) copied incorrectly

• Incorrect signature algorithm

• Check if the request parameters and their order meet the API requirements.

Solution:

1. Ensure the AccessKey and AccessKey secret set in your code are exactly the same as those you obtained from the console. Check for extra spaces or special characters. Use an existing AccessKey or create a new one. For more information, see Create an AccessKey pair. Note: To reduce the risk of AccessKey leakage, the AccessKey secret is displayed only once when it is created and cannot be viewed later. Be sure to store it securely.

2. Upgrade the commons-codec version to avoid potential signature calculation errors:

   Update the dependency:

   Maven

   Modify the pom.xml file.

   <dependency>
      <groupId>commons-codec</groupId>
      <artifactId>commons-codec</artifactId>
      <version>1.15</version> <!-- Updated version -->
   </dependency>

   After updating the version number, run the following command:

   mvn clean install

   Gradle

   In the build.gradle file, add or update the dependency:

   dependencies {
        implementation 'commons-codec:commons-codec:1.15' // Updated version
   }

   Run the following command to build the project:

   gradle build

3. If you are using self-signing, carefully check if the code logic is consistent with what is described in V3 request body & signature mechanism.

SDK.EndpointResolvingError: "No such region 'cn-XX'. Please check your region ID".

The direct cause of this issue is that the SDK version is too old and does not support calls to new regions or APIs. Solution:

Upgrade the SDK dependency version:

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>aliyun-java-sdk-core</artifactId>
  <version>4.7.2</version>
</dependency>

dependencies {
    implementation 'com.aliyun:aliyun-java-sdk-core:4.7.2'
    implementation 'com.aliyun:aliyun-java-sdk-sts:3.1.2'
}

Failed to instantiate [com.aliyuncs.IAcsClient]: Factory method 'iAcsClient' threw exception with message: org/apache/http/conn/ssl/DefaultHostnameVerifier .

The direct cause of this issue is using an incompatible version of the Apache HttpClient library with the Alibaba Cloud SDK, which resulted in an error. Solution:

• If the project uses multiple dependency libraries, ensure that no other library introduces an incompatible version of HttpClient. Review this by manual inspection or using the dependency management feature of your build tool.

• The Apache HttpClient version is too old. We recommend updating to version 4.5.14 or later.

  <dependency>
      <groupId>org.apache.httpcomponents.client</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.14</version> <!-- Please check for the latest version -->
  </dependency>

Error when calling an OpenAPI: code: 401, You have not activated the XXX service, or a similar message.

This error indicates that the Alibaba Cloud account you are using has not enabled or activated the corresponding service. XXX represents the specific service name, such as OCR service. Solution:

1. Log on to the management console of the corresponding service.

2. Find and enable the required feature.

3. Wait for the service to be enabled and then call the API again.

Failed to get RAM session credentials from ECS metadata service. HttpCode=XX

The instance RAM role (ecs_ram_role) credential can only be used in an ECS or ECI instance, and a RAM role must be attached to the instance. For more information, see ECS instance RAM role and Use an ECI instance RAM role by calling an API.

• To verify if you can use this credential in your project, run the following command in the ECS instance:

  • Linux instance

    # Get the metadata access credential. You must set an expiration time. The request cannot contain the X-Forwarded-For header. 100.100.100.200 is the IPv4 address of the instance metadata service.
    TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<metadata_credential_expiration_time>"`
    # Access instance metadata
    curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/ram/security-credentials/[role-name]

  • Windows instance (PowerShell)

    # Get the metadata access credential. You must set an expiration time. The request cannot contain the X-Forwarded-For header. 100.100.100.200 is the IPv4 address of the instance metadata service.
    $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<metadata_credential_expiration_time>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
    # Access instance metadata
    Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/ram/security-credentials/[role-name]

  If the following content is returned, your project can use the instance RAM role (ecs_ram_role) credential on the instance.

  {
    "AccessKeyId" : "AccessKeyIdValue",
    "AccessKeySecret" : "AccessKeySecretValue",
    "Expiration" : "2025-07-10T08:37:58Z",
    "SecurityToken" : "SecurityTokenValue",
    "LastUpdated" : "2025-07-10T02:33:26Z",
    "Code" : "Success"
  }

• If you want to switch to a different credential, see Manage access credentials.

There is a risk of leakage of this AccessKey

Cause: If the response contains this message, your AK may be at risk of being leaked. Alibaba Cloud has taken restrictive protective measures for the AK.

Solution: For more information, see Solutions for AccessKey leakage.

Request was denied due to api flow control

Cause: The SDK is called too frequently, which may cause the server to return an error, such as "ThrottlingException".

Solution:

• Implement a request retry mechanism and increase the time interval between requests as needed to reduce the load.

• Optimize the code logic. Consider using batch processing or asynchronous invocation to reduce the number of API requests.

Specified access key denied due to access policy

Cause: An AccessKey network access restriction policy is configured. This policy restricts the source IP addresses that can use a permanent AccessKey to make API requests.

Solution:

• Modify the IP address range in the AccessKey network access restriction policy.

• Do not enable the AccessKey network access restriction policy.

For more information, see AccessKey network access restriction policy.

com.aliyuncs.exceptions.ClientException: SDK.InvalidRegionId : Can not find endpoint to access

Cause: Incorrect parameter settings, such as an incorrect regionId, can cause the service to fail or return an error.

Solution:

• Refer to the documentation and code examples provided by Alibaba Cloud to ensure all configuration parameters, such as Endpoint, RegionId, and other request parameters, are filled in correctly.

• You can debug the API in the OpenAPI Developer Portal. After the debugging is successful, download the complete sample project code for local debugging.

The solutions above help you use the Alibaba Cloud SDK. If you encounter other issues, contact us in the following ways:

• Submit a ticket: Alibaba Cloud Ticket Submission Page.

• If you have related needs or feedback, you can add the DingTalk group to contact Alibaba Cloud technical support. The group number is 60965016010.