apache/dubbo · error · IllegalArgumentException

Cannot found key in url param:{key}

Error message

Cannot found key in url param:{key}

What it means

Thrown by DynamicParamTable.getValueIndex when the requested param key is not registered in the global KEY2INDEX table. DynamicParamTable is Dubbo's internal compact-URL optimization: it maps known param keys to integer offsets to shrink serialized URL size. Calling getValueIndex with a key that no loaded DynamicParamSource extension contributed is treated as a programming error, not a missing-data condition.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/url/component/param/DynamicParamTable.java:60

        throw new IllegalStateException();
    }

    static {
        init();
    }

    public static int getKeyIndex(boolean enabled, String key) {
        if (!enabled) {
            return -1;
        }
        Integer indexFromMap = KEY2INDEX.get(key);
        return indexFromMap == null ? -1 : indexFromMap;
    }

    public static int getValueIndex(String key, String value) {
        int idx = getKeyIndex(true, key);
        if (idx < 0) {
            throw new IllegalArgumentException("Cannot found key in url param:" + key);
        }
        ParamValue paramValue = VALUES[idx];
        return paramValue.getIndex(value);
    }

    public static String getKey(int offset) {
        return ORIGIN_KEYS[offset];
    }

    public static String getValue(int vi, int offset) {
        return VALUES[vi].getN(offset);
    }

    private static void init() {
        List<String> keys = new LinkedList<>();
        List<ParamValue> values = new LinkedList<>();
        Map<String, Integer> key2Index = new HashMap<>(64);
        keys.add("");

View on GitHub (pinned to 3a3043227f)

Solutions

1. Confirm the param key is contributed by a registered DynamicParamSource extension; check META-INF/dubbo SPI files and that the extension loads.
2. If you are extending Dubbo's param set, register your DynamicParamSource so the key lands in KEY2INDEX during init().
3. If calling internally, first check getKeyIndex(true, key) >= 0 before calling getValueIndex to avoid the throw.
4. Verify Dubbo versions across modules match so the known-key set is consistent.

Example fix

// before
int vi = DynamicParamTable.getValueIndex("my.custom.key", "v"); // throws if key unregistered

// after
int idx = DynamicParamTable.getKeyIndex(true, "my.custom.key");
if (idx < 0) {
    // key not managed by compact table; handle without compaction
    return;
}
int vi = DynamicParamTable.getValueIndex("my.custom.key", "v");

String key = "...", value = "...";
if (DynamicParamTable.getKeyIndex(true, key) < 0) {
    // key not managed by the compact param table; skip compaction
    return;
}
int vi = DynamicParamTable.getValueIndex(key, value);

static boolean isKnownParamKey(String key) {
    return DynamicParamTable.getKeyIndex(true, key) >= 0;
}

try {
    int vi = DynamicParamTable.getValueIndex(key, value);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Cannot found key in url param")) {
        // key not registered; fall back to non-compact handling
    } else throw e;
}

When it happens

Trigger: DynamicParamTable.getValueIndex(key, value) is called with a key absent from KEY2INDEX (getKeyIndex returns -1). This is an internal API invoked during URL compaction/expansion. It fires when the param-key set the caller uses is out of sync with the DynamicParamSource extensions registered in the current FrameworkModel.

Common situations: Custom DynamicParamSource SPI extensions that are not loaded (missing META-INF/dubbo entry, wrong classpath), a Dubbo version mismatch where param keys were renamed/removed, or internal code paths that query a param key before the static initializer finishes populating the table. End users rarely call this directly.

Related errors

• the array size of values should be larger than 0
• URL Param Cache is full.
• unrecognized value {value} , please check if value is illega
• There is no merger to merge result.
• No such class name in {}

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