apache/dubbo · error · IllegalStateException

Protocol not found: <id>

Error message

Protocol not found: <id>

What it means

Thrown by ServiceConfigBase.convertProtocolIdsToProtocols when a specific protocol id (from the comma-separated protocolIds) cannot be found in the config manager. Each referenced id must resolve to a registered ProtocolConfig.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/ServiceConfigBase.java:263

    protected void convertProtocolIdsToProtocols() {
        if (StringUtils.isEmpty(protocolIds)) {
            if (CollectionUtils.isEmpty(protocols)) {
                List<ProtocolConfig> protocolConfigs = getConfigManager().getDefaultProtocols();
                if (CollectionUtils.isEmpty(protocolConfigs)) {
                    throw new IllegalStateException("The default protocol has not been initialized.");
                }
                setProtocols(protocolConfigs);
            }
        } else {
            String[] idsArray = COMMA_SPLIT_PATTERN.split(protocolIds);
            Set<String> idsSet = new LinkedHashSet<>(Arrays.asList(idsArray));
            List<ProtocolConfig> tmpProtocols = new ArrayList<>();
            for (String id : idsSet) {
                Optional<ProtocolConfig> globalProtocol = getConfigManager().getProtocol(id);
                if (globalProtocol.isPresent()) {
                    tmpProtocols.add(globalProtocol.get());
                } else {
                    throw new IllegalStateException("Protocol not found: " + id);
                }
            }
            setProtocols(tmpProtocols);
        }
    }

    public Class<?> getInterfaceClass() {
        if (interfaceClass != null) {
            return interfaceClass;
        }
        if (ref instanceof GenericService) {
            return GenericService.class;
        }
        try {
            if (StringUtils.isNotEmpty(interfaceName)) {
                interfaceClass = Class.forName(
                        interfaceName, true, Thread.currentThread().getContextClassLoader());
            }

View on GitHub (pinned to 3a3043227f)

Solutions

1. Correct the protocol id to match an existing registered ProtocolConfig's id.
2. Register the missing ProtocolConfig bean/property with the expected id in the same scope.
3. Remove the stale id from protocolIds if that protocol is no longer needed.

Example fix

// before
@DubboService(protocol = "dubbo,rst") // typo: should be 'rest'

// after
@DubboService(protocol = "dubbo,rest")

// Validate every protocol id resolves before export
for (String id : serviceConfig.getProtocolIds().split(",")) {
    if (!configManager.getProtocol(id.trim()).isPresent()) {
        throw new IllegalStateException("Unknown protocol id: " + id.trim()
            + "; register it first");
    }
}
serviceConfig.export();

try {
    serviceConfig.export();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Protocol not found: ")) {
        // correct the protocol id or register the missing ProtocolConfig, then retry
    }
    throw e;
}

When it happens

Trigger: protocolIds is non-empty and is split into ids, but getConfigManager().getProtocol(id) returns an empty Optional for at least one id.

Common situations: Typo in a protocol id in dubbo.protocol.ids or @DubboService(protocol=...). Protocol bean defined with a different id than referenced. ProtocolConfig registered in a different scope/module than the service. Removed a protocol bean but kept references to its id.

Related errors

• url missing protocol: "${fullURLStr}"
• ref not allow null!
• The class <getClassDesc(ref.getClass())> unimplemented inter
• The default protocol has not been initialized.
• The interface class <interfaceClass> is not a interface!

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/d994f013c5ca7aa7. Report an issue: GitHub.