stanfordnlp/CoreNLP · error · SsurgeonParseException

Cannot manually change a document ID. If you need an…

Error message

Cannot manually change a document ID.  If you need an operation to change an entire sentence's document ID, please file an issue on github.

What it means

The third guarded key is "docID": a node's document identifier is sentence-level metadata that the SemanticGraph relies on, so per-node edits are forbidden. checkIllegalAttributes throws SsurgeonParseException when the attributes map contains "docID".

Solutions

  1. Remove "docID" from the attributes map.
  2. Rename the document by updating the docID on the sentence/annotation object before Ssurgeon processing, not via node attributes.
  3. Sanitize attribute maps with a filter that drops docID, sentIndex, and idx before constructing Ssurgeon operations.

Example fix

// before
attrs.put("docID", "doc-42");
attrs.put("lemma", "run");

// after
attrs.remove("docID"); // change docID at the sentence/document level instead
attrs.put("lemma", "run");
Defensive patterns

Strategy: validation

Validate before calling

// Java
Set<String> forbidden = Set.of("idx", "sentIndex", "docID");
attrs.keySet().removeAll(forbidden); // or reject if present

Try / catch

// Java
try {
  AddDep.checkIllegalAttributes(attrs);
} catch (SsurgeonParseException e) {
  // drop the offending metadata key and retry with content attributes only
}

Prevention

When it happens

Trigger: An AddDep edit whose attributes map includes key "docID"; thrown at rule-construction time from AddDep.checkIllegalAttributes.

Common situations: Bulk-copying CoreLabel annotations into AddDep attributes; attempting per-token document renaming inside Ssurgeon instead of rewriting document metadata at the document level.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/semgraph/semgrex/ssurgeon/AddDep.java:162

      SsurgeonUtils.moveNode(sg, sm, newNode, newIndex);
    }

    return true;
  }

  /**
   * Certain attributes cannot be edited, especially docid, sentid, idx,
   * or they mess up the hashmaps in the SemanticGraph
   */
  public static void checkIllegalAttributes(Map<String, String> attributes) {
    if (attributes.containsKey("idx")) {
      throw new SsurgeonParseException("Cannot manually set the index attribute.  If you need a moveWord operation, please file an issue on github.");
    }
    if (attributes.containsKey("sentIndex")) {
      throw new SsurgeonParseException("Cannot manually change the sentence index.  If you need an operation to change an entire sentence's sentIndex, please file an issue on github.");
    }
    if (attributes.containsKey("docID")) {
      throw new SsurgeonParseException("Cannot manually change a document ID.  If you need an operation to change an entire sentence's document ID, please file an issue on github.");
    }

    // if there's an exception, we'll barf when creating the pattern rather than at runtime
    try {
      CoreLabel newNodeObj = fromCheapStrings(attributes);
    } catch (UnsupportedOperationException e) {
      throw new SsurgeonParseException("Unable to process node attribute keys for Ssurgeon operation", e);
    }
  }

  /**
   * Given the keys and values of the CoreAnnotation attributes,
   * build a CoreLabel to use as the new word
   */
  public static CoreLabel fromCheapStrings(Map<String, String> attributes) {
    String[] keys = new String[attributes.size()];
    String[] values = new String[attributes.size()];
    int idx = 0;

View on GitHub (pinned to 1b7edd19c4)