stanfordnlp/CoreNLP · error · SsurgeonParseException

Parsing Ssurgeon args: unknown flag

Error message

Parsing Ssurgeon args: unknown flag ${argsKey}

What it means

parseArgsBox maps '-flag value' pairs to SsurgeonArgs fields. For flags that are not one of the known built-in ones, the flag text (minus leading '-') is looked up via AnnotationLookup.toCoreKey as a CoreAnnotations key; if it is not a valid core key, SsurgeonParseException is thrown with the unknown flag name.

Solutions

  1. Check the flag spelling against the Ssurgeon documentation for that edit type (e.g. -node, -nodes, -reln, -lemma).
  2. If you intended a CoreAnnotation, use a key name that AnnotationLookup.toCoreKey recognizes (e.g. -pos, -lemma, -ner).
  3. Remove flags not supported by your CoreNLP version; check the changelog for renamed flags.
  4. Catch SsurgeonParseException at rule-load time and log the whole edit line to spot the bad flag.

Example fix

// before
editnode -node node -rel sndep:obj
// after
editnode -node node -reln nsubj
Defensive patterns

Strategy: validation

Validate before calling

Set<String> known = Set.of("-node","-nodes","-reln","-gov","-dep","-edge","-lemma","-pos","-ner","-value","-position","-weight");
for (String flag : flags) {
  if (!known.contains(flag) && AnnotationLookup.toCoreKey(flag.substring(1)) == null)
    throw new IllegalArgumentException("Unknown ssurgeon flag: " + flag);
}

Try / catch

try { SsurgeonEdit.parseEditLine(line, attrs, language); } catch (SsurgeonParseException e) { if (e.getMessage().startsWith("Parsing Ssurgeon args")) log.error("Unknown flag, check spelling: " + e.getMessage()); }

Prevention

When it happens

Trigger: An edit line containing a flag like -myflag or -lemna (typo of -lemma) that matches no known Ssurgeon flag and is also not resolvable to a CoreAnnotation key via AnnotationLookup.toCoreKey.

Common situations: Typos in flag names (-node vs -nodes, -reln vs -rel); using flags from an older/newer CoreNLP version where the flag list changed; inventing flags expecting them to be ignored; passing annotation keys that don't exist in AnnotationLookup.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/semgraph/semgrex/ssurgeon/Ssurgeon.java:582

        case POSITION_ARG:
          argsBox.position = argsValue;
          break;
        case UPDATE_MORPHO_FEATURES:
        case UPDATE_MORPHO_FEATURES_LOWER:
          argsBox.updateMorphoFeatures = argsValue;
          break;
        case REMOVE:
          argsBox.remove.add(argsValue);
          break;
        case REMOVE_MORPHO_FEATURES:
        case REMOVE_MORPHO_FEATURES_LOWER:
          argsBox.removeMorphoFeatures.add(argsValue);
          break;
        default:
          String key = argsKey.substring(1);
          Class<? extends CoreAnnotation<?>> annotation = AnnotationLookup.toCoreKey(key);
          if (annotation == null) {
            throw new SsurgeonParseException("Parsing Ssurgeon args: unknown flag " + argsKey);
          }
          argsBox.annotations.put(key, argsValue);
      }
    }
    return argsBox;
  }

  /**
   * Given a string entry, converts it into a SsurgeonEdit object.
   */
  public static SsurgeonEdit parseEditLine(String editLine, Map<String, String> attributeArgs, Language language) {
    try {
      // Extract the operation name first
      final String[] tuples1 = editLine.split("\\s+", 2);
      if (tuples1.length < 1) {
        throw new SsurgeonParseException("Error in SsurgeonEdit.parseEditLine: invalid number of arguments");
      }
      final String command = tuples1[0];

View on GitHub (pinned to 1b7edd19c4)