What causes "NOTCONSOLE not paired with a snippet" in elastic/elasticsearch?

Position the `// NOTCONSOLE` directive so it attaches to an open snippet, or remove it if its snippet is gone.

elastic/elasticsearch · error · InvalidUserDataException

NOTCONSOLE not paired with a snippet

Error message

NOTCONSOLE not paired with a snippet

What it means

Thrown by SnippetParser.consoleHandled() in the NOTCONSOLE branch when a line matching the NOTCONSOLE regex is found but the `snippet` parameter (the snippet passed into consoleHandled) is null. This is the NOTCONSOLE analog of error 212: a NOTCONSOLE directive with no open snippet to attach to. Note the null check here uses the method's `snippet` argument, while the CONSOLE branch uses the `snippetBuilder` field — both refer to the active snippet.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/SnippetParser.java:236

            }
            return true;
        }
        return false;
    }

    protected boolean consoleHandled(String line, SnippetBuilder snippet) {
        if (line.matches(getConsoleRegex())) {
            if (snippetBuilder == null) {
                throw new InvalidUserDataException("CONSOLE not paired with a snippet");
            }
            if (snippetBuilder.consoleDefined()) {
                throw new InvalidUserDataException("Can't be both CONSOLE and NOTCONSOLE");
            }
            snippetBuilder.withConsole(Boolean.TRUE);
            return true;
        } else if (line.matches(getNotconsoleRegex())) {
            if (snippet == null) {
                throw new InvalidUserDataException("NOTCONSOLE not paired with a snippet");
            }
            if (snippetBuilder.consoleDefined()) {
                throw new InvalidUserDataException("Can't be both CONSOLE and NOTCONSOLE");
            }
            snippet.withConsole(Boolean.FALSE);
            return true;
        }
        return false;
    }

    protected abstract String getTestSetupRegex();

    protected abstract String getTeardownRegex();

    protected abstract String getConsoleRegex();

    protected abstract String getNotconsoleRegex();

View on GitHub (pinned to db6a809a66)

Solutions

Position the `// NOTCONSOLE` directive so it attaches to an open snippet, or remove it if its snippet is gone.
Confirm the snippet-opening syntax is recognized by the parser so a snippet is actually open when NOTCONSOLE is reached.

Example fix

// before:
// NOTCONSOLE
// (no source block)
// after:
----
echo hello
----
// NOTCONSOLE

Defensive patterns

Strategy: validation

Validate before calling

// Before building, walk doc lines and ensure every // NOTCONSOLE has an open snippet to attach to.

Prevention

Always pair `// NOTCONSOLE` with an open snippet.
Remove orphaned `// NOTCONSOLE` when its snippet is deleted.
Confirm the snippet-opening syntax is recognized by the parser.

When it happens

Trigger: A `// NOTCONSOLE` line appears with no currently-open snippet. The getNotconsoleRegex matches and the passed snippet is null.

Common situations: An orphaned `// NOTCONSOLE` left after its source block was deleted; the directive placed before any snippet opens; a copy-paste artifact.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/1a0da96b1d5a1cab. Report an issue: GitHub.