karatelabs/karate · error · ParserException

invalid : parenthesized destructuring pattern

Error message

invalid ${siteName}: parenthesized destructuring pattern

What it means

Karate's parser rejects a destructuring target that was wrapped in parentheses, e.g. `([a, b]) = arr` or `var ({a}) = obj`. Per spec, ObjectLiteral/ArrayLiteral inside parentheses does NOT refine to a destructuring pattern, so the parenthesized form is invalid in binding or assignment position. The message includes the site name for context.

Solutions

  1. Remove the parentheses around the array/object literal so it refines to a pattern: `[a, b] = arr`
  2. For assignment-position ambiguity cases, keep the pattern bare rather than parenthesized
  3. Rewrite as separate binding/assignment statements if the structure is complex

Example fix

// before
([a, b]) = arr; // parenthesized pattern
// after
[a, b] = arr;
Defensive patterns

Strategy: validation

Validate before calling

// flag parenthesized array/object literals in assignment/binding position
if (/\(\s*\[[^\]]*\]\s*\)\s*=[^=]/.test(src) || /\(\s*\{[^}]*\}\s*\)\s*=[^=]/.test(src)) {
  throw new Error('parenthesized destructuring pattern is invalid; remove the parentheses');
}

Try / catch

try {
  runScript(src);
} catch (e) {
  if (String(e).includes('parenthesized destructuring pattern')) {
    // remove surrounding parens around the pattern
  }
  throw e;
}

Prevention

When it happens

Trigger: Parsing `([a, b]) = arr;` or `for (const ([x]) of ...)` — after unwrapping PAREN_EXPR, inner is a LIT_EXPR whose first child is LIT_ARRAY or LIT_OBJECT, triggering the error.

Common situations: Adding 'protective' parentheses around a destructuring pattern; code adapted from languages where parens are neutral; confusion about the `(a, b) = ...` ambiguity resolution that requires the pattern NOT to be parenthesized.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/parser/JsParser.java:1706

        // ObjectLiteral or ArrayLiteral does NOT refine to a destructuring pattern,
        // so it becomes invalid; everything else falls through to the simple check.
        while (n.type == NodeType.PAREN_EXPR) {
            // PAREN_EXPR shape: [(, body, )]
            Node body = n.size() >= 2 ? n.get(1) : null;
            if (body == null) {
                throw new ParserException("invalid " + siteName);
            }
            if (body.type == NodeType.EXPR_LIST && body.size() != 1) {
                throw new ParserException("invalid " + siteName + ": comma expression");
            }
            Node inner = stripExprWrappers(body);
            if (inner == null) {
                throw new ParserException("invalid " + siteName);
            }
            if (inner.type == NodeType.LIT_EXPR && inner.size() >= 1) {
                NodeType lit = inner.getFirst().type;
                if (lit == NodeType.LIT_ARRAY || lit == NodeType.LIT_OBJECT) {
                    throw new ParserException("invalid " + siteName + ": parenthesized destructuring pattern");
                }
            }
            n = inner;
        }
        switch (n.type) {
            case REF_EXPR -> {
                // REF_EXPR is single-arg arrow `x => ...` when its first child is an
                // FN_ARROW_EXPR rather than the IDENT token; that form is invalid.
                if (n.size() >= 1 && !n.getFirst().isToken()
                        && n.getFirst().type == NodeType.FN_ARROW_EXPR) {
                    throw new ParserException("invalid " + siteName + ": arrow function");
                }
                // `this` lexes as IDENT (see JsLexer.keywordOrIdent) but per spec
                // the ThisExpression has AssignmentTargetType=invalid.
                if (n.size() >= 1 && n.getFirst().isToken()
                        && n.getFirst().token.type == IDENT
                        && "this".equals(n.getFirst().getText())) {
                    throw new ParserException("invalid " + siteName + ": this");

View on GitHub (pinned to a22eb90246)