karatelabs/karate · error · RangeError

The normalization form should be one of NFC, NFD, NFKC, NFKD

Error message

The normalization form should be one of NFC, NFD, NFKC, NFKD

What it means

This RangeError is thrown by String.prototype.normalize when the argument is not one of the four accepted normalization forms: NFC, NFD, NFKC, NFKD. Any other string (including lowercase variants like 'nfc', or unrelated values) fails the switch and raises the error. Omitting the argument or passing undefined defaults to NFC and is safe.

Solutions

1. Pass one of the exact forms: 'NFC', 'NFD', 'NFKC', or 'NFKD'
2. Normalize case before calling: s.normalize(form.toUpperCase())
3. Whitelist-validate: if (['NFC','NFD','NFKC','NFKD'].includes(form)) before invoking

Example fix

// before
s.normalize(form); // RangeError when form = 'nfc'
// after
s.normalize(form.toUpperCase()); // or validate against the 4 allowed forms first

const VALID_FORMS = ['NFC','NFD','NFKC','NFKD']; const canNormalize = (f) => f === undefined || VALID_FORMS.includes(f);

const isNormalizationForm = (f) => typeof f === 'string' && ['NFC','NFD','NFKC','NFKD'].includes(f);

try { return s.normalize(form); } catch (e) { if (e.name === 'RangeError') return s.normalize(); /* NFC default */ throw e; }

When it happens

Trigger: Calling 'str'.normalize('Nfc') (case-sensitive check), 'str'.normalize('UTF8'), or 'str'.normalize(customForm) where the form string comes from configuration or user input.

Common situations: Form names read from config files or CLI options with inconsistent casing; confusion with encoding names like UTF-8; uppercasing forgotten when normalizing user-supplied form names.

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

• Invalid code point
• Invalid count value
• array index too large for dense storage:
• Cannot convert non-finite number to BigInt
• Cannot convert non-integer number to BigInt

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/be72ef3cb09df401. Report an issue: GitHub.

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/js/JsStringPrototype.java:703

        int index = argInt(args, 0, 0);
        if (index < 0) {
            index = s.length() + index;
        }
        if (index < 0 || index >= s.length()) {
            return Terms.UNDEFINED;
        }
        return String.valueOf(s.charAt(index));
    }

    private Object normalize(Context context, Object[] args) {
        String s = thisString(context, "normalize");
        String form = (args.length > 0 && args[0] != Terms.UNDEFINED) ? argString(args, 0, context) : "NFC";
        return switch (form) {
            case "NFC" -> java.text.Normalizer.normalize(s, java.text.Normalizer.Form.NFC);
            case "NFD" -> java.text.Normalizer.normalize(s, java.text.Normalizer.Form.NFD);
            case "NFKC" -> java.text.Normalizer.normalize(s, java.text.Normalizer.Form.NFKC);
            case "NFKD" -> java.text.Normalizer.normalize(s, java.text.Normalizer.Form.NFKD);
            default -> throw JsErrorException.rangeError("The normalization form should be one of NFC, NFD, NFKC, NFKD");
        };
    }

    private Object localeCompare(Context context, Object[] args) {
        String s = thisString(context, "localeCompare");
        String other = argString(args, 0, context);
        return Integer.signum(s.compareToIgnoreCase(other));
    }

}

View on GitHub (pinned to a22eb90246)