stanfordnlp/CoreNLP · error · IllegalArgumentException

Please specify -stage, either OLD or NEW

Error message

Please specify -stage, either OLD or NEW

What it means

ConvertModels.main parses the -stage property and calls Stage.valueOf on it. A missing property (NullPointerException) or a value not matching the OLD/NEW enum (IllegalArgumentException) is rethrown as 'Please specify -stage, either OLD or NEW'.

Solutions

  1. Add -stage OLD or -stage NEW to the command line
  2. Check the spelling/case of the -stage value (valueOf uppercases input, so any case works if the word is right)
  3. Run with only the supported values; inspect the Stage enum for valid names

Example fix

// before
java edu.stanford.nlp.neural.ConvertModels -model SENTIMENT -input in.gz -output out.gz
// after
java edu.stanford.nlp.neural.ConvertModels -stage NEW -model SENTIMENT -input in.gz -output out.gz
Defensive patterns

Strategy: validation

Validate before calling

String stage = System.getProperty("stage", System.getenv("STAGE"));
if (stage == null || !(stage.equalsIgnoreCase("OLD") || stage.equalsIgnoreCase("NEW"))) {
  throw new IllegalArgumentException("-stage must be OLD or NEW");
}

Try / catch

try {
  ConvertModels.main(args);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("-stage")) {
    System.err.println("Usage: ... -stage OLD|NEW -model ... -input ... -output ...");
    System.exit(2);
  }
  throw e;
}

Prevention

When it happens

Trigger: Running the ConvertModels main without -stage, with an empty -stage, or with a value other than OLD or NEW (case-insensitive).

Common situations: Command-line misconfiguration when converting legacy (OLD) models to the new (NEW) format; typos like 'new-model' or lowercase-agnostic values that still don't match.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/edu/stanford/nlp/neural/ConvertModels.java:379

   * <code> java edu.stanford.nlp.neural.ConvertModels -stage NEW -model EMBEDDING -input /scr/nlp/data/coref/models/neural/english/english-embeddings.INT.ser.gz -output /scr/nlp/data/coref/models/neural/english/english-embeddings.e39.ser.gz</code>
   * <br>
   * There is another coref model which isn't used in corenlp, but it might be in the future.  To upgrade this, use <code>-model FASTCOREF</code>
   * <br>
   * <code> java edu.stanford.nlp.neural.ConvertModels -stage OLD -model FASTCOREF -input /scr/nlp/data/coref/models/fastneural/fast-english-model.e38.ser.gz -output /scr/nlp/data/coref/models/fastneural/fast-english-model.INT.ser.gz</code>
   * <br>
   * <code> java edu.stanford.nlp.neural.ConvertModels -stage NEW -model FASTCOREF -input /scr/nlp/data/coref/models/fastneural/fast-english-model.INT.ser.gz -output /scr/nlp/data/coref/models/fastneural/fast-english-model.e39.ser.gz</code>
   * <br>
   *
   * @author <a href=horatio@gmail.com>John Bauer</a>
   */
  public static void main(String[] args) throws IOException, ClassNotFoundException, InstantiationException, NoSuchMethodException {
    Properties props = StringUtils.argsToProperties(args);

    final Stage stage;
    try {
      stage = Stage.valueOf(props.getProperty("stage").toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException | NullPointerException e) {
      throw new IllegalArgumentException("Please specify -stage, either OLD or NEW");
    }

    final Model modelType;
    try {
      modelType = Model.valueOf(props.getProperty("model").toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException | NullPointerException e) {
      throw new IllegalArgumentException("Please specify -model, either SENTIMENT, DVPARSER, EMBEDDING, COREF, FASTCOREF");
    }

    if (!props.containsKey("input")) {
      throw new IllegalArgumentException("Please specify -input");
    }

    if (!props.containsKey("output")) {
      throw new IllegalArgumentException("Please specify -output");
    }

    String inputPath = props.getProperty("input");

View on GitHub (pinned to 1b7edd19c4)