apache/skywalking · error · IllegalArgumentException

Unknown DSL catalog: {wireName}

Error message

Unknown DSL catalog: {wireName}

What it means

Catalog.of() resolves the wire name of a DSL rule's catalog (the 'catalog' field in MAL/LAL/OAL-style rule YAML shipped to the OAP) to the Catalog enum. An unrecognized wire name means the rule was authored against a different vocabulary or a newer/older OAP version; rather than silently dropping the rule, the resolver throws IllegalArgumentException. This is the fail-fast contract documented on the method itself.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/dsl/Catalog.java:56

    @Getter
    private final String wireName;

    Catalog(final String wireName) {
        this.wireName = wireName;
    }

    /**
     * Resolve {@code wireName} to the matching enum. Throws {@link IllegalArgumentException} on
     * an unknown catalog so callers fail fast rather than silently dropping the rule.
     */
    public static Catalog of(final String wireName) {
        for (final Catalog c : values()) {
            if (c.wireName.equals(wireName)) {
                return c;
            }
        }
        throw new IllegalArgumentException("Unknown DSL catalog: " + wireName);
    }
}

View on GitHub (pinned to 102af09b4a)

Solutions

1. Check the error message for the offending wireName and correct it to a catalog the running OAP version supports (exact casing).
2. Look up the accepted values in the Catalog enum of the OAP version you deploy (values() are compared literally).
3. If the rule comes from a newer feature, upgrade OAP to a version that knows that catalog before shipping the rule.
4. Re-apply the corrected rule via the same channel (file or runtime rule API) and restart/reload.

Example fix

# before (rule yaml)
catalog: METER_RULEZ

# after
catalog: METER_RULE

// Whitelist catalogs before applying a rule
Set<String> known = Arrays.stream(Catalog.values()).map(Catalog::getWireName).collect(Collectors.toSet());
if (!known.contains(rule.getCatalog())) {
    throw new IllegalArgumentException("unsupported catalog: " + rule.getCatalog());
}

// Java: resolve to enum safely
Optional<Catalog> c = Arrays.stream(Catalog.values())
    .filter(x -> x.getWireName().equals(wireName)).findFirst();
if (!c.isPresent()) { /* reject rule with clear operator message */ }

try { Catalog c = Catalog.of(wireName); } catch (IllegalArgumentException e) { log.error("rejecting rule with unknown catalog {}", wireName); /* quarantine rule, alert operator */ }

When it happens

Trigger: A DSL configuration file or runtime rule payload (e.g. via the rule-management API / agent-rule sync) provides a 'catalog' string that does not equal any Catalog enum's wireName (comparison is exact, case-sensitive c.wireName.equals(wireName)).

Common situations: Upgrading/downgrading OAP while keeping custom MAL/LAL rules whose catalog vocabulary changed; typos or wrong casing in the catalog field; hand-writing a rule with an invented catalog value; tooling generating rules from an outdated schema.

Related errors

• hierarchy-definition.yml {layer} is not a valid layer name.
• hierarchy-definition.yml layer-levels: {layer} is not defin
• hierarchy-definition.yml layer-levels: {lowerLayer} is not
• hierarchy-definition.yml hierarchy: {layer} layer-level shou
• service-name can't be empty

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/645fb4381ce6b3fa. Report an issue: GitHub.