All Products
Search

This Product

    Microservices Engine:MSE Nacos SDK applications and restricted Nacos SDK versions

    Document Center

    Microservices Engine:MSE Nacos SDK applications and restricted Nacos SDK versions

    Last Updated:Mar 11, 2026

    Microservices Engine (MSE) Nacos provides service registration, discovery, and configuration management through SDKs for multiple languages. Use this guide to choose the right SDK for your technology stack and avoid SDK versions with known stability issues.

    Minimum recommended SDK versions

    For stability and compatibility, use at least the following versions:

    SDK Minimum recommended version
    Java (Nacos Client) 2.3.2 or later
    Go (nacos-sdk-go) 2.3.3 or later (Professional Edition), 1.1.6 or later (Basic Edition)
    Python (nacos-sdk-python) 2.0.7 or later
    Dubbo 2.7.20 or later (2.x), 3.1.6 or later (3.x)
    Spring Cloud Alibaba 2.2.6.RELEASE or later

    For details on specific versions to avoid, see the Restricted SDK versions section below.

    Select an SDK for your technology stack

    Java

    Integration Description Reference
    Native SDK Connect directly through the Nacos Java SDK. Java SDK
    Spring Boot Use Nacos as a service registry and configuration center within Spring Boot. Nacos with Spring Boot
    Spring Cloud Integrate Nacos with Spring Cloud for configuration management. Nacos with Spring Cloud
    Dubbo Register Dubbo services with Nacos for high-performance remote procedure call (RPC). Dubbo on MSE

    Go

    Integration Description Reference
    Native SDK Set up a service registry and configuration center with the Go SDK. nacos-sdk-go
    Dubbo-Go Build RPC services in Go with Apache Dubbo-Go and Nacos. Dubbo-Go
    Kitex Use Kitex, an RPC framework for Go microservices with built-in Nacos service registry support. -

    Node.js

    Integration Description Reference
    Native SDK Implement service registration and discovery with the Node.js SDK. nacos-sdk-nodejs

    Python

    Integration Description Reference
    Native SDK Build a microservice system with the Python SDK. nacos-sdk-python

    Service mesh (Istio)

    MSE Nacos integrates with the Istio service mesh ecosystem through the Mesh Configuration Protocol (MCP) standard. To connect Nacos with service mesh, see Create a service source.

    Restricted SDK versions

    Certain SDK versions have known bugs that can cause service outages, performance degradation, or data issues. Avoid the versions listed below and upgrade to the recommended alternatives.

    Java SDK (Nacos Client)

    Restricted versions Issue Action
    0.x - 1.1.x No support for lightweight service heartbeats. Oversized heartbeat packets degrade performance. Details. Upgrade to 1.2.0 or later.
    1.4.1 - 1.4.2 1.4.1: If DNS is unavailable and domain name resolution fails, the heartbeat thread exits unexpectedly. The service goes offline and cannot recover automatically. Details. 1.4.2: The getConfigAndSignListener API returns plaintext content when querying an encrypted configuration. Upgrade to 1.4.3 or later.
    2.0.0 - 2.0.1 Cannot carry RAM identity information. After you enable client authentication on the engine, the client cannot obtain configurations, register services, or discover services, even if the required information is configured. Upgrade to 2.0.2 or later.
    2.2.0 - 2.2.1 When deploying through EDAS or SAE, the -Dnacos.use.endpoint.parsing.rule=false and -Dnacos.use.cloud.namespace.parsing=false JVM parameters do not take effect. This prevents the application from connecting to the MSE Nacos cluster. Upgrade to 2.2.2 or later.
    2.3.1 The server pushes configuration updates repeatedly even when the configuration has not changed. This causes unnecessary CPU and network overhead and may affect stability. Details. Upgrade to 2.3.2 or later.

    Go SDK (nacos-sdk-go)

    Restricted versions Issue Action
    1.0.1 - 1.1.3 The client always reports its version as 1.0.1, which prevents accurate version identification. Two critical bugs may cause frequent change notifications or heartbeat interruptions. Basic Edition: upgrade to 1.1.6 or later. Professional Edition: upgrade to 2.3.2 or later.
    1.1.4 If a subscribed configuration is deleted, the client continuously queries the non-existent service. The resulting flood of configuration query requests can trigger rate limiting and affect other applications. Details. Upgrade to a version later than 1.1.4. For recommended minimum versions, see the Minimum recommended SDK versions table above.
    2.0.0 - 2.1.0 The client always reports its version as 2.0.0, which prevents accurate version identification. After a reconnection, instances do not automatically re-register or re-subscribe to services. The service goes offline and cannot recover. Details. Upgrade to 2.3.3 or later.
    2.2.7 - 2.3.1 The client always reports its version as 2.2.7, which prevents accurate version identification. Two critical bugs may cause failure to receive service change notifications or service loss after a connection interruption. Upgrade to 2.3.3 or later.

    Python SDK (nacos-sdk-python)

    Restricted versions Issue Action
    2.0.0 - 2.0.6 After a reconnection, the client does not automatically re-register or re-subscribe to services and configurations. This leads to service interruptions with no automatic recovery. Upgrade to 2.0.7 or later.

    Dubbo

    Restricted versions Issue Action
    2.7.5 and earlier When subscribing to multiple services, changes to a provider's address list are not retrieved. Traffic may be routed to an offline or non-existent provider. Details. Upgrade to 2.7.6 or later.
    2.7.8 Creates an excessive number of Nacos Client instances, causing a sharp increase in connections and threads that affects both client and server stability. Details. Upgrade to 2.7.9 or later.
    2.7.11 Depends on Nacos-Java-Client 1.4.1 by default (a restricted version). Upgrade to 2.7.12 or later, or explicitly set the Nacos Client version to 1.4.2 or later.
    2.7.19 and earlier When Dubbo subscribes to a service, it subscribes to multiple service names. During address list aggregation, the consumer may fail to find the provider. Details. Upgrade to 2.7.20 or later.
    3.0.0 - 3.1.5 Contains known issues that affect stability. Upgrade to 3.1.6 or later.

    Spring Cloud Alibaba

    Restricted versions Issue Action
    Earlier than 2.2.4 Overwrites the Nacos Client log configuration. Nacos logs are written to the application's business logs, which complicates troubleshooting. Details. Upgrade to 2.2.6.RELEASE or later.
    2.2.4.RELEASE, 2.2.5.RELEASE Depends on Nacos-Java-Client 1.4.1 by default (a restricted version). Upgrade to 2.2.6.RELEASE or later, or explicitly set the Nacos Client version to 1.4.2 or later.

    Upgrade your Nacos SDK

    1. Identify the SDK and version your application currently uses (check pom.xml, go.mod, requirements.txt, or package.json).

    2. Check the tables above to confirm the target version.

    3. Update the dependency version in your build configuration file.

    4. Rebuild and test the application in a staging environment.

    5. Deploy the updated application.

    Note: MSE manages the server-side Nacos version. The tables above apply to the client SDK bundled with your application.