stanfordnlp/CoreNLP · critical · RuntimeException

ChineseEnglishWordMap cannot find dictionary

Error message

ChineseEnglishWordMap cannot find dictionary

What it means

CEDict backs ChineseEnglishWordMap with a dictionary file located via a default path and, failing that, an environment variable (ENV_VARIABLE). If neither location is readable, the static path() method throws a RuntimeException — the dictionary is mandatory, so initialization aborts. This is a class-loading/initialization-time failure: any use of ChineseEnglishWordMap hits it.

Solutions

1. Set the environment variable expected by CEDict (ENV_VARIABLE, e.g. pointing at cedict data) to a readable dictionary file path
2. Place the dictionary file at the default path the class checks first (defaultPath/defaultPath2)
3. Verify file permissions with ls/File.canRead() — the file must be readable by the JVM process user
4. Reinstall/bundle the dictionary resource with the application (e.g. copy it into the deployment image) and catch the RuntimeException to surface a friendlier setup message

Example fix

// before
WordMap wm = new ChineseEnglishWordMap(); // throws: cannot find dictionary

// after
// export CEDICT_HOME=/opt/data/cedict_ts.u8  (shell), or defensively:
try {
  WordMap wm = new ChineseEnglishWordMap();
} catch (RuntimeException e) {
  throw new IllegalStateException("Install CEDict dictionary and set its env var", e);
}

// fail fast at startup with a clear message
String env = System.getenv("CEDICT_HOME"); // the variable CEDict's ENV_VARIABLE expects
if (env == null || !new File(env).canRead())
  throw new IllegalStateException("Set CEDICT_HOME to a readable CEDict dictionary file");

static boolean cedictAvailable() {
  String env = System.getenv("CEDICT_HOME");
  return env != null && new File(env).canRead();
}

try {
  ChineseEnglishWordMap map = new ChineseEnglishWordMap();
} catch (RuntimeException e) {
  if (e.getMessage().contains("cannot find dictionary")) {
    throw new IllegalStateException("Missing CEDict dictionary: install file or set env var", e);
  }
  throw e;
}

When it happens

Trigger: Instantiating or statically touching ChineseEnglishWordMap/CEDict when the default dictionary path does not exist and the environment variable (CE_HOME-style) is unset or points to a non-readable file.

Common situations: Deploying to a machine where the CEDict data file was never installed; container images that omitted the data files; running after a library upgrade that changed the expected default path; environment variable renamed or not exported in the runtime shell.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Class at path
• Class is in classpath multiple times
• Could not load class in jar:
• Could not load tokenizer factory
• Could not set option

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

Appendix: source

Thrown at src/edu/stanford/nlp/trees/international/pennchinese/CEDict.java:22

public class CEDict {
  private static final String defaultPath = "cedict_ts.u8";
  private static final String defaultPath2 = "/u/nlp/data/chinese-english-dictionary/cedict_ts.u8";
  private static final String ENV_VARIABLE = "CEDICT";

  public static String path() {
    File f = new File(defaultPath);
    if (f.canRead()) {
      return defaultPath;
    } else {
      f = new File(defaultPath2);
      if (f.canRead()) {
        return defaultPath2;
      } else {
        String path = System.getenv(ENV_VARIABLE);
        f = new File(path);
        if ( ! f.canRead()) {
          throw new RuntimeException("ChineseEnglishWordMap cannot find dictionary");
        }
        return path;
      }
    }
  }

  private CEDict() {} // static methods only
}

View on GitHub (pinned to 1b7edd19c4)