apache/dubbo · error · UnsupportedOperationException

setScopeModel is forbidden for ServiceAddressURL

Error message

setScopeModel is forbidden for ServiceAddressURL

What it means

UnsupportedOperationException thrown by ServiceAddressURL.setScopeModel() because ServiceAddressURL is a read-only composite URL that delegates getScopeModel() to its wrapped consumerURL. A ServiceAddressURL represents a provider address paired with a consumer's configuration — the scope model belongs to the consumer, not the address, so mutating it on the address URL is semantically meaningless and explicitly forbidden. Callers must set the scope model on the underlying consumerURL instead.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/url/component/ServiceAddressURL.java:220

    @Override
    public int hashCode() {
        return super.hashCode();
    }

    @Override
    public ScopeModel getScopeModel() {
        return consumerURL.getScopeModel();
    }

    @Override
    public ServiceModel getServiceModel() {
        return consumerURL.getServiceModel();
    }

    @Override
    public URL setScopeModel(ScopeModel scopeModel) {
        throw new UnsupportedOperationException("setScopeModel is forbidden for ServiceAddressURL");
    }

    @Override
    public URL setServiceModel(ServiceModel serviceModel) {
        throw new UnsupportedOperationException("setServiceModel is forbidden for ServiceAddressURL");
    }

    /**
     * ignore consumer url compare.
     * It's only meaningful for comparing two address urls related to the same consumerURL.
     *
     * @param obj
     * @return
     */
    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;

View on GitHub (pinned to 3a3043227f)

Solutions

1. Do not call setScopeModel() on ServiceAddressURL — set it on the consumer URL (accessible via getConsumerURL()) or the originating URL instead.
2. Add a type check before calling setScopeModel(): if (url instanceof ServiceAddressURL) skip or redirect to the consumer URL.
3. Review custom SPI/filter code for generic URL mutation patterns and make them aware of ServiceAddressURL's immutability contract.

Example fix

// before — generic mutation fails on ServiceAddressURL
url.setScopeModel(scopeModel); // throws if url is ServiceAddressURL

// after — set on the appropriate URL
if (url instanceof ServiceAddressURL) {
    ((ServiceAddressURL) url).getConsumerURL().setScopeModel(scopeModel);
} else {
    url.setScopeModel(scopeModel);
}

// Check URL type before calling setScopeModel
if (url instanceof ServiceAddressURL) {
    // scope model belongs to the consumer URL — set it there
    ((ServiceAddressURL) url).getConsumerURL().setScopeModel(scopeModel);
} else {
    url.setScopeModel(scopeModel);
}

public static boolean isMutableScopeModel(URL url) {
    return !(url instanceof ServiceAddressURL);
}

try {
    url.setScopeModel(scopeModel);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("forbidden for ServiceAddressURL")) {
        // redirect to consumer URL
        if (url instanceof ServiceAddressURL) {
            ((ServiceAddressURL) url).getConsumerURL().setScopeModel(scopeModel);
        }
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling setScopeModel() on an instance of ServiceAddressURL (or its concrete subclass). This URL type is constructed internally by Dubbo's registry/cluster layer when resolving provider addresses. Application or framework code that generically calls setScopeModel() on any URL without checking the concrete type will hit this.

Common situations: Generic URL-processing code (filters, custom SPI extensions, interceptors) that calls setScopeModel() on a URL that happens to be a ServiceAddressURL; migration to Dubbo 3.x where ServiceAddressURL became stricter about mutability; code that previously set scope model on address URLs in older Dubbo versions.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• setServiceModel is forbidden for ServiceAddressURL
• Invalid scope model, expect to be a ModuleModel but got: <sc
• Invalid url, password without username!
• defaultValue <= 0
• Invalid url, password without username!

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