stanfordnlp/CoreNLP · error · MatchException

Match failed!

Error message

Match failed!

What it means

AceCharSeq.match() attempts to locate an entity's character extent within a token stream and record the resulting token Span. If both start and end are not found (negative), it throws MatchException('Match failed!'), meaning the ACE entity extent could not be aligned to any tokens.

Solutions

1. Ensure the .apf.xml and .sgm files are a matching pair from the same document.
2. Verify offsets are character offsets consistent with the exact source text handed to the tokenizer (watch for XML entity vs raw character offsets).
3. Skip or log documents/entities whose extents fall outside tokens instead of failing the whole parse.
4. Re-run corpus preprocessing so tokens cover the full extent range.

Example fix

// before
for (String doc : docs) reader.parse(doc);
// after
try {
  reader.parse(doc);
} catch (MatchException e) {
  logger.warning("skipping unmatchable document: " + doc);
}

if (extentStart < 0 || extentEnd >= docText.length()) {
  logger.warning("extent out of bounds, skipping: " + docId);
  return;
}

try {
  reader.parseDocument(docId);
} catch (MatchException e) {
  logger.warning("token alignment failed for " + docId + ": " + e.getMessage());
}

When it happens

Trigger: Parsing ACE 2005 .apf.xml files where an entity/extent's start/end offsets do not fall within the tokenized document — typically when the .apf annotation offsets disagree with the .sgm source text (e.g. mismatched file pair, wrong docId, or extents referencing text not in the tokens list).

Common situations: Mismatched or incomplete ACE corpus files, annotation offsets counted in bytes vs characters when non-ASCII text is present, feeding the reader a .sgm with preprocessing that stripped characters the offsets refer to.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Invalid relation mention argument role
• Bad data format:
• attempt to get word when sentence and lattice are null!
• Attempt to use ExternalFiniteDifference without passing…
• Attempted to parse empty/null tag

AI-assisted analysis of stanfordnlp/CoreNLP@1b7edd19c4 (2026-09-10). Data as JSON: /api/errors/a808d44d3e93eb18. Report an issue: GitHub.

Appendix: source

Thrown at src/edu/stanford/nlp/ie/machinereading/domains/ace/reader/AceCharSeq.java:153

      }

      //
      // we do not tokenize dashed-words, hence the end may be inside a token
      // e.g. Conference => Conference-leading
      // the same situation will happen due to (uncommon) annotation errors
      //
      else if (mByteOffset.end() >= tokens.get(i).getByteOffset().start()
          && mByteOffset.end() < tokens.get(i).getByteOffset().end() - 1) {
        end = i;
        break;
      }
    }

    if (start >= 0 && end >= 0) {
      mTokenOffset = new Span(start, end);
      // mPhrase = makePhrase(tokens, mTokenOffset);
    } else {
      throw new MatchException("Match failed!");
    }
  }

  @Override
  public String toString() {
    return "AceCharSeq [mByteOffset=" + mByteOffset + ", mText=" + mText
        + ", mTokenOffset=" + mTokenOffset + ']';
  }

  /*
   * private AceToken makePhrase(Vector<AceToken> tokens, Span span) {
   * StringBuilder word = new StringBuilder(); StringBuilder lemma = new
   * StringBuilder(); StringBuilder pos = new StringBuilder(); StringBuilder chunk =
   * new StringBuilder(); StringBuilder nerc = new StringBuilder();
   *
   * for(int i = span.mStart; i <= span.mEnd; i ++){ if(i > span.mStart){
   * word.append("_"); lemma.append("_"); pos.append("_"); chunk.append("_");
   * nerc.append("_"); }

View on GitHub (pinned to 1b7edd19c4)