apache/dubbo · error · IllegalArgumentException

Invalid scope model, expect to be a ModuleModel but got: <sc

Error message

Invalid scope model, expect to be a ModuleModel but got: <scopeModel>

What it means

Thrown by AbstractMethodConfig.checkScopeModel() when the ScopeModel attached to a method-level config is not a ModuleModel. Dubbo 3.x uses a hierarchical scope model (ApplicationModel > ModuleModel); method configs are inherently module-scoped, so attaching an ApplicationModel or other ScopeModel subtype is invalid. This guard enforces the correct level of the config object tree.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/AbstractMethodConfig.java:121

        super(moduleModel);
    }

    @Override
    @Transient
    public ModuleModel getScopeModel() {
        return (ModuleModel) super.getScopeModel();
    }

    @Override
    @Transient
    protected ScopeModel getDefaultModel() {
        return ApplicationModel.defaultModel().getDefaultModule();
    }

    @Override
    protected void checkScopeModel(ScopeModel scopeModel) {
        if (!(scopeModel instanceof ModuleModel)) {
            throw new IllegalArgumentException(
                    "Invalid scope model, expect to be a ModuleModel but got: " + scopeModel);
        }
    }

    @Transient
    protected ModuleConfigManager getModuleConfigManager() {
        return getScopeModel().getConfigManager();
    }

    public Integer getForks() {
        return forks;
    }

    public void setForks(Integer forks) {
        this.forks = forks;
    }

    public Integer getTimeout() {

View on GitHub (pinned to 3a3043227f)

Solutions

Pass a ModuleModel to setScopeModel(), obtained via applicationModel.getDefaultModule() or a specific module.
Avoid setting the scope model manually; let Dubbo assign the default model (getDefaultModel() returns the default module).
Ensure configs created within the same module share that module's ModuleModel.

Example fix

// before
methodConfig.setScopeModel(applicationModel); // wrong level
// after
methodConfig.setScopeModel(applicationModel.getDefaultModule());

Defensive patterns

Strategy: type-guard

Validate before calling

ModuleModel module = applicationModel.getDefaultModule();
if (!(module instanceof ModuleModel)) {
    throw new IllegalStateException("Expected ModuleModel");
}
methodConfig.setScopeModel(module);

Type guard

static boolean isModuleScoped(ScopeModel model) {
    return model instanceof org.apache.dubbo.rpc.model.ModuleModel;
}

Try / catch

try {
    methodConfig.setScopeModel(model);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("ModuleModel")) {
        methodConfig.setScopeModel(applicationModel.getDefaultModule());
    } else throw e;
}

Prevention

Prefer applicationModel.getDefaultModule() over passing application-level models.
Avoid manually setting scope model unless necessary; rely on defaults.
In custom bootstrap, log the scope model class before assignment.

When it happens

Trigger: Programmatically calling config.setScopeModel() with an ApplicationModel instance instead of a ModuleModel on a MethodConfig (or subclass). Building configs manually outside the normal bootstrap path and injecting the wrong scope model level.

Common situations: Migrating from Dubbo 2.x where scope models did not exist and incorrectly passing the application-level model. Mixing FrameworkModel/ApplicationModel/ModuleModel when constructing configs in custom bootstrap code.

Related errors

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