apache/dolphinscheduler · error · IllegalArgumentException

Invalid subscribe scope

Error message

Invalid subscribe scope 

What it means

IllegalArgumentException thrown by JdbcRegistryDataChangeListenerAdapter.isPathMatch when a subscriber's subscribe scope is not one of the known enum values (PATH_ONLY, CHILDREN_ONLY, ALL). This is an internal invariant: the scope comes from the subscribe API, so it indicates a corrupted/unknown enum passed through.

Source

Thrown at dolphinscheduler-registry/dolphinscheduler-registry-plugins/dolphinscheduler-registry-jdbc/src/main/java/org/apache/dolphinscheduler/plugin/registry/jdbc/JdbcRegistryDataChangeListenerAdapter.java:88

                .eventData(value)
                .type(Event.Type.ADD)
                .build();
        listener.notify(event);
    }

    private boolean isPathMatch(final String subscribePath,
                                final String eventPath,
                                final SubscribeListener.SubscribeScope subscribeScope) {
        switch (subscribeScope) {
            case PATH_ONLY:
                return KeyUtils.isSamePath(subscribePath, eventPath);
            case CHILDREN_ONLY:
                return KeyUtils.isParent(subscribePath, eventPath);
            case ALL:
                return KeyUtils.isParent(subscribePath, eventPath)
                        || KeyUtils.isSamePath(subscribePath, eventPath);
            default:
                throw new IllegalArgumentException("Invalid subscribe scope " + subscribeScope);
        }
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Register listeners with a valid SubscribeScope: PATH_ONLY, CHILDREN_ONLY, or ALL
2. Never pass null as the subscribe scope
3. Check for version mismatch between modules after an upgrade
4. Grep for custom enum extensions of SubscribeScope and remove them

Example fix

// before
registry.subscribe(path, listener, null);
// after
registry.subscribe(path, listener, SubscribeScope.ALL);

if (scope != SubscribeScope.PATH_ONLY && scope != SubscribeScope.CHILDREN_ONLY && scope != SubscribeScope.ALL) throw new IllegalArgumentException("bad scope");

if (scope instanceof SubscribeScope && java.util.EnumSet.of(SubscribeScope.PATH_ONLY, SubscribeScope.CHILDREN_ONLY, SubscribeScope.ALL).contains(scope)) { /* valid */ }

try { registry.subscribe(path, listener, scope); } catch (IllegalArgumentException e) { log.error("invalid subscribe scope", e); }

When it happens

Trigger: A change event (added/changed/deleted) fires for a subscribed path and the adapter's switch hits the default branch because the stored subscribeScope value is null or an unrecognized enum constant (e.g. after an enum change between versions).

Common situations: Custom code registering a listener with a null or custom scope; incompatibility after upgrading where enum constants were renamed; deserialized state carrying an obsolete scope.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• requestType is not a valid value
• contentType is not a valid value
• The execType: {execType} is invalid
• The releaseState {releaseState} is illegal, please check it.
• no master server available

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/05fa943fe4cc4f90. Report an issue: GitHub.