Why Adding uniqueId to @SofaReference Breaks Service Lookup and How to Fix It

On November 11 a user reported an exception in a sandbox file‑upload scenario: the AxxxCore TR interface failed because a dependent SOFA JVM service could not be found.

can not find the corresponding JVM service. Please check if there is a SOFA deployment publish the corresponding JVM service. If this exception occurred when the application starts up, please add Require-Module to SOFA deployment's MANIFEST.MF to indicate the startup dependency of SOFA modules.

The investigation revealed a recent code change that added uniqueId = "aftsFileClient" to an @SofaReference annotation.

@SofaReference(uniqueId = "aftsFileClient")
private AftsFileClient aftsFileClient;

In SOFA, a Bundle (similar to a Maven module) must declare its META-INF/MANIFEST.MF and module metadata. Each Bundle has its own Spring context, and inter‑Bundle communication occurs via JVM services published with @SofaService and referenced with @SofaReference . 1. Module A publishes a JVM service with @SofaService . 2. Module B references that service with @SofaReference .

The core question was: why does adding uniqueId trigger the error?

Problem Analysis – step 1

Hypothesis: without uniqueId the framework may fall back to searching within the same Bundle, while adding it forces a strict cross‑Bundle lookup.

Experiments in the same Bundle:

@Service
@SofaService
public class JvmBeanTestServiceImpl implements JvmBeanTestService {
    @Override
    public String test() { return "test1"; }
}

@Service
public class JvmBeanTestV2ServiceImpl implements JvmBeanTestV2Service {
    @Override
    public String testV2() { return "testV2"; }
}

@Service
@SofaService
public class JvmBeanTestRunTimeServiceImpl implements JvmBeanTestRunTimeService {
    @SofaReference
    private JvmBeanTestService jvmBeanTestService;

    @SofaReference
    private JvmBeanTestV2Service jvmBeanTestV2Service;

    @Override
    public String runTest1() { return jvmBeanTestService.test(); }

    @Override
    public String runTest2() { return jvmBeanTestV2Service.testV2(); }
}

Results:

Calling jvmBeanTestService succeeded – same‑Bundle JVM services can be referenced, contradicting the official documentation.

Calling jvmBeanTestV2Service failed – @SofaReference matches only JVM services, not plain beans.

Problem Analysis – step 2

The next suspicion was that the service publishing side omitted uniqueId while the reference side specified it. SOFA matches services by interface name + uniqueId; if the publisher does not declare the same uniqueId, the lookup fails.

<sofa:service ref="aftsFileClient" interface="com.alipay.aaa.client.AftsFileClient"/>

In this case the developer added uniqueId to the reference because a new configuration required a new service instance, but the original service was still published without uniqueId, leading to the mismatch.

Code changes involved:

<bean id="aftsFileXxxClient" class="com.alipay.aaa.client.impl.AftsFileXxxClientImpl" init-method="init">
    <property name="env" value="xxx" />
    <property name="sysName" value="yyy" />
    <property name="appId" value="zzz" />
    <property name="bizKey" value="ttt" />
</bean>

<bean id="xxxAftsFileClient" class="com.alipay.xxx.common.service.integration.afts.impl.XxxAftsFileClientImpl"/>
<sofa:service ref="xxxAftsFileClient" interface="com.alipay.xxx.common.service.integration.afts.XxxAftsFileClient"/>

Since the new JVM service implements a different interface, there was no need to use uniqueId at all; the old code could remain unchanged.

Additional Diagnosis

Another hidden cause was the health‑check configuration com.alipay.sofa.boot.skipJvmReferenceHealthCheck=true. Changing it to false prevented the application from starting, revealing that the health‑check setting also influences service discovery failures.

Lesson: always ensure that both publisher and consumer agree on uniqueId when using it, verify Bundle boundaries, and be aware of health‑check flags that may mask underlying issues.