karatelabs/karate · warning

configure logging.mask: no usable rules — set at least one…

Error message

configure logging.mask: no usable rules — set at least one of headers / jsonPaths / patterns. mask is OFF.

What it means

A `logging.mask` configure map was supplied but none of its rule lists (`headers`, `jsonPaths`, `patterns`) yielded any usable rules, so masking would silently do nothing. The library warns and returns null — the mask is OFF — rather than installing an empty mask.

Solutions

  1. Add at least one rule under `headers`, `jsonPaths`, or `patterns`
  2. Verify key spellings: `headers`, `jsonPaths`, `patterns` (case-sensitive)
  3. If patterns were intended, fix the per-entry warnings (missing/invalid regex) logged before this one
  4. Remove the empty mask configure call if masking is not needed

Example fix

// before
karate.configure('logging.mask', { patterns: [] })
// after
karate.configure('logging.mask', { headers: ['Authorization'], jsonPaths: ['$.password'] })
Defensive patterns

Strategy: validation

Validate before calling

if (headers.isEmpty() && jsonPaths.isEmpty() && patterns.isEmpty())
    throw new IllegalStateException("logging.mask has no rules; mask would be OFF");

Prevention

When it happens

Trigger: `karate.configure('logging.mask', {})`; a mask map where all lists are empty arrays; a map where every patterns entry was skipped (missing/invalid regex, per errors 880/881) leaving zero usable rules.

Common situations: Configuring masking with keys mistyped so nothing was parsed (`header` instead of `headers`); all pattern regexes invalid so the list drained to empty; leftover empty mask config from removed rules.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/output/LogMask.java:137

                    String repStr = rep == null ? replacement : rep.toString();
                    try {
                        patternRules.add(new PatternRule(Pattern.compile(regex.toString()), repStr));
                    } catch (PatternSyntaxException e) {
                        // Skip rather than fail-fast — a typo in one rule shouldn't blow up
                        // the whole config-js eval. The warn names the entry so the user
                        // can find it. Other rules in the same mask still apply.
                        logger.warn("configure logging.mask.patterns[{}] invalid regex '{}': {} — skipped",
                                idx, regex, e.getDescription());
                    }
                }
                idx++;
            }
        }
        JavaCallable enableForUri = map.get("enableForUri") instanceof JavaCallable c ? c : null;
        if (headers.isEmpty() && jsonPaths.isEmpty() && patternRules.isEmpty()) {
            // User provided a mask map but every rule list is empty / invalid. Without this
            // warn the mask silently does nothing, which is hard to debug.
            logger.warn("configure logging.mask: no usable rules — set at least one of "
                    + "headers / jsonPaths / patterns. mask is OFF.");
            return null;
        }
        return new LogMask(headers, jsonPaths, patternRules, replacement, enableForUri);
    }

    /**
     * One-line description of mask rule counts, e.g.
     * {@code "3 headers, 2 jsonPaths, 1 pattern"}. Used by the per-scenario
     * "mask active" debug log so users can verify their config compiled.
     */
    public String describe() {
        int h = maskedHeadersLower.size();
        int j = jsonPaths.size();
        int p = patternRules.size();
        return h + (h == 1 ? " header, " : " headers, ")
                + j + (j == 1 ? " jsonPath, " : " jsonPaths, ")
                + p + (p == 1 ? " pattern" : " patterns");

View on GitHub (pinned to a22eb90246)