What causes "unknown parse failure" in xai-org/x-algorithm?

Inspect the cause (e) chained on the ParseFailure — the real exception explains the failure

xai-org/x-algorithm · error · ParseFailure

unknown parse failure

Error message

unknown parse failure

What it means

Fallback ParseFailure thrown by Parser.parseParams when the underlying exception is not a RecognitionException carrying position info. It indicates the parse blew up in a way the error-enrichment logic could not classify, so no line/column can be reported; the original exception is attached as the cause.

Source

Thrown at botmaker/src/java/com/twitter/botmaker/compiler/Parser.java:160

      if (e.getCause() instanceof RecognitionException) {
        RecognitionException re = (RecognitionException) e.getCause();
        String extraMsg = "";
        if (re.token != null) {
          String unexpectedTok = "<EOF>";
          if (re.getUnexpectedType() >= 0) {
            unexpectedTok = BotMakerParser.tokenNames[re.getUnexpectedType()];
          }
          extraMsg = String.format(
              ": line %d col %d, near token <%s>: unexpected token %s",
              re.token.getLine(), re.token.getCharPositionInLine() + 1,
              re.token.getText(), unexpectedTok);
        } else if (re.line != 0) {
          extraMsg = String.format(": line %d col %d", re.line, re.charPositionInLine + 1);
        }
        throw new ParseFailure(String.format(
            "Failed to parse DF signature '%s'%s", s, extraMsg), re);
      }
      throw new ParseFailure("unknown parse failure", e);
    }

    return buildParams(root);
  }

  private static ImmutableList<Tuple3<Tree, String, Optional<Tree>>> buildParams(
      Tree params) throws ParseFailure {
    ImmutableList.Builder<Tuple3<Tree, String, Optional<Tree>>> ret = ImmutableList.builder();
    Set<String> argNames = Sets.newHashSet();
    boolean hasOpt = false;
    for (int i = 0; i < params.getChildCount(); i++) {
      Tree arg = params.getChild(i);
      if (arg.getType() == BotMakerLexer.ARG) {
        String name = arg.getChild(1).getText();
        if (arg.getChildCount() == 2 && hasOpt) {
          throw new ParseFailure(
              String.format(
                  "Non-optional parameter %s must be declared before optional parameters.",

View on GitHub (pinned to 24c60942c5)

Solutions

Inspect the cause (e) chained on the ParseFailure — the real exception explains the failure
Reproduce with the exact input string in a unit test and narrow to the smallest failing fragment
Check for ANTLR/parser-class version mismatch after dependency upgrades
If the cause is a lexer crash, fix or reject the offending character sequence before parsing

Defensive patterns

Strategy: try-catch

Try / catch

catch (ParseFailure pf) {
  Throwable cause = pf.getCause();
  log.error("Unknown parse failure; cause:", cause);
  // report input + cause to maintainers
}

Prevention

Pin the ANTLR version used to generate the parser
Fuzz-test the parser with odd inputs to find lexer crashes
Always log the chained cause, not just the message

When it happens

Trigger: parseParams hits a non-recognition exception from ANTLR: a null token, lexer error that escapes as a generic RuntimeException, or an internal error tree walk (e.g. buildParams on a malformed root) rather than a pure syntax error.

Common situations: Rare, ambiguous failures during grammar/runtime version mismatches (ANTLR version change altering exception types), corrupted generated parser classes, or edge-case inputs that crash the lexer instead of failing cleanly.

Related errors

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/10c2d89b5d35fc94. Report an issue: GitHub.