SCA 2023.X — Troubleshooting and Fixing the Nacos Bootstrap Config Failure

Issue source: spring-cloud-alibaba#3931
Affected versions: spring-cloud-alibaba 2023.0.1.3+

1. Problem Description

In Spring Cloud Alibaba 2023.X, placing Nacos config (including extension-configs, shared-configs, etc.) in bootstrap.yml / bootstrap.properties causes the config center’s content to fail to load properly, even though the logs show the bootstrap file itself was read.

Moving the same config to application.yml makes everything work again.

2. Root Cause

flowchart TD
    A[bootstrap.yml is read] --> B{SCA version check}
    B -- 2023.0.1.2 and earlier --> C[✅ Nacos config center loads normally]
    B -- 2023.0.1.3 and later --> D[❌ extension-configs / shared-configs fail]
    D --> E[Root cause: SCA 2023.0.1.3 changed the config-load priority mechanism]
    E --> F[Nacos PropertySource registered in the bootstrap phase is overwritten or discarded by later steps]

In short:
SCA 2023.0.1.3 made a backward-incompatible internal change, causing the Nacos extension config in bootstrap.yml to be “dropped” in the loading chain, while config in application.yml takes the new path and is unaffected.

3. Solutions

✅ Option 1 (recommended): migrate to application.yml (the official recommended approach)

SCA 2023.X has fully shifted to the spring.config.import mechanism and no longer uses bootstrap as the primary entry point.

# application.yml
spring:
  application:
    name: your-service
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        namespace: your-namespace
        group: DEFAULT_GROUP
        file-extension: yaml
        extension-configs:
          - data-id: common.yaml
            group: DEFAULT_GROUP
            refresh: true
        shared-configs:
          - data-id: shared.yaml
            group: DEFAULT_GROUP
            refresh: true
  config:
    import:
      - nacos:your-service.yaml

✅ Option 2: version rollback (stopgap)

If the project can’t migrate the config files for now, you can roll back to 2023.0.1.2:

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-alibaba-dependencies</artifactId>
    <version>2023.0.1.2</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

⚠️ This is only a transition; running an old version long-term is not advised.

⚠️ Ineffective option (verified)

Adding the spring-cloud-starter-bootstrap dependency does not solve this problem:

<!-- ❌ Adding this doesn't help -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

Reason: bootstrap.yml itself is already being read (visible in the logs); the problem is in the later processing stage of the Nacos extension config, not that the bootstrap context failed to start.

4. Config-Load Priority (the new 2023.X mechanism)

flowchart TD
    A[bootstrap.properties] --> B[Nacos config center]
    B --> C[application.properties]
    C --> D[Final effective config]

Note: under the new 2023.X chain, priority from low to high is:
bootstrap → Nacos config center → application
That is, the Nacos config center’s values can override bootstrap, but are overridden by same-named config in application.
This differs from the old behavior — pay special attention when migrating.

5. Summary