apache/dubbo · error · IllegalArgumentException

unrecognized value {value} , please check if value is illega

Error message

unrecognized value {value} , please check if value is illegal. Permitted values: {values}

What it means

Thrown by FixedParamValue.getIndex when the requested value (lowercased) is not among the permitted values supplied at construction. FixedParamValue enforces a closed value set; any value outside it is rejected because the compact-table encoding has no slot for it. The message lists the allowed values to aid diagnosis.

Source

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

            }
        }
        val2Index = Collections.unmodifiableMap(valueMap);
    }

    /**
     * DEFAULT value will be returned if n = 0
     * @param n
     */
    @Override
    public String getN(int n) {
        return values[n];
    }

    @Override
    public int getIndex(String value) {
        Integer offset = val2Index.get(value.toLowerCase(Locale.ROOT));
        if (offset == null) {
            throw new IllegalArgumentException("unrecognized value " + value
                    + " , please check if value is illegal. " + "Permitted values: "
                    + Arrays.asList(values));
        }
        return offset;
    }
}

View on GitHub (pinned to 3a3043227f)

Solutions

1. Read the 'Permitted values' list in the message and correct the offending value to one of them.
2. If the value is legitimately new, extend the FixedParamValue's allowed set in the relevant DynamicParamSource extension (requires rebuild/redeploy).
3. If the value set cannot be enumerated ahead of time, switch that key to DynamicValues so unknown values are interned dynamically.

Example fix

// before
FixedParamValue pv = new FixedParamValue("true", "false");
pv.getIndex("tru"); // throws

// after
pv.getIndex("true");
// or make the set open:
new DynamicValues(null).getIndex("tru");

FixedParamValue pv = /* ... */;
String value = "...";
// pre-check membership
if (pv.getIndex(value) < 0) { /* not in set */ }
// note: getIndex throws on miss, so guard before calling in best-effort code

// Best-effort: catch to test membership
static boolean isPermitted(FixedParamValue pv, String value) {
    try { pv.getIndex(value); return true; }
    catch (IllegalArgumentException e) { return false; }
}

try {
    int idx = pv.getIndex(value);
} catch (IllegalArgumentException e) {
    // value not in permitted set; use a default or reject the URL
}

When it happens

Trigger: FixedParamValue.getIndex(value) is called where value.toLowerCase() is not a key in val2Index. Triggered during URL param compaction when a URL carries a value for a fixed-set key that was not declared in the FixedParamValue's values array.

Common situations: A new/typo'd enum-like param value appears in a URL (e.g. 'tru' instead of 'true' for a boolean key), or a custom DynamicParamSource declares a fixed set that is incomplete relative to what producers actually emit. Version skew between producer and consumer param sets also triggers it.

Related errors

• Cannot found key in url param:{key}
• URL Param Cache is full.
• the array size of values should be larger than 0
• Invalid configurator rule, please specify at least one param
• service field in configuration is null.

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