infinilabs/analysis-ik · error · IllegalStateException

ik dict has not been initialized yet, please call initial me

Error message

ik dict has not been initialized yet, please call initial method first.

What it means

Dictionary is a singleton that must be primed by the static method Dictionary.initial(Configuration) before any dictionary-dependent API runs; getSingleton() throws IllegalStateException when that initialization has not happened. Most library code paths (CJKSegmenter, CN_QuantifierSegmenter, AnalyzeContext stopword filtering, Monitor reload) call Dictionary.getSingleton() internally, so the exception usually surfaces from inside a tokenization call rather than from user code directly.

Source

Thrown at core/src/main/java/org/wltea/analyzer/dic/Dictionary.java:293

				}
			}
		}
		return remoteExtStopWordDictFiles;
	}

	private String getDictRoot() {
		return conf_dir.toAbsolutePath().toString();
	}


	/**
	 * 获取词典单子实例
	 * 
	 * @return Dictionary 单例对象
	 */
	public static Dictionary getSingleton() {
		if (singleton == null) {
			throw new IllegalStateException("ik dict has not been initialized yet, please call initial method first.");
		}
		return singleton;
	}


	/**
	 * 批量加载新词条
	 * 
	 * @param words
	 *            Collection<String>词条列表
	 */
	public void addWords(Collection<String> words) {
		if (words != null) {
			for (String word : words) {
				if (word != null) {
					// 批量加载词条到主内存词典中
					singleton._MainDict.fillSegment(word.trim().toCharArray());
				}

View on GitHub (pinned to 6d2d70fd1a)

Solutions

Call Dictionary.initial(DefaultConfig.getInstance()) once at application/test startup (static initializer, @BeforeAll, or context-listener) before the first IKAnalyzer/IKTokenizer use
For custom configuration (ext/remote dictionaries), build your Configuration (e.g. DefaultConfig with a known conf dir) and pass that to initial instead of the default
If the error appears mid-run in a container environment, check for duplicate IK jars across classloaders and keep exactly one copy so the initialized singleton and the consumers are the same class
Wrap first-use in a small ensureInitialized() helper so every entry point cheaply guarantees initial was called

Example fix

// before — throws IllegalStateException on first token
IKAnalyzer analyzer = new IKAnalyzer(true);
analyzer.tokenize(...);

// after — initialize the singleton once before first use
Dictionary.initial(DefaultConfig.getInstance());
IKAnalyzer analyzer = new IKAnalyzer(true);
analyzer.tokenize(...);

Defensive patterns

Strategy: validation

Validate before calling

private static volatile boolean ikInitialized;
static void ensureIkInitialized() {
    if (!ikInitialized) {
        synchronized (IkInit.class) {
            if (!ikInitialized) {
                Dictionary.initial(DefaultConfig.getInstance());
                ikInitialized = true;
            }
        }
    }
}
// call ensureIkInitialized() before creating IKAnalyzer or touching Dictionary

Try / catch

try {
    Dictionary.getSingleton().addWords(words);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("not been initialized")) {
        Dictionary.initial(DefaultConfig.getInstance());
        Dictionary.getSingleton().addWords(words); // retry once after init
    } else {
        throw e;
    }
}

Prevention

Initialize the dictionary in a static initializer or app lifecycle hook so it cannot be skipped
In test suites, put Dictionary.initial in a shared @BeforeAll rather than each test constructing analyzers ad hoc
Keep exactly one copy of the IK jar in the classpath/classloader hierarchy to avoid a second uninitialized Dictionary class
Document that this fork requires explicit Dictionary.initial — older IK versions self-initialized lazily, so copied-in legacy code will break

When it happens

Trigger: Calling Dictionary.getSingleton(), or any API that reaches it — new IKAnalyzer(...)/IKTokenizer tokenization, addWords/removeWords, Dictionary.matchInMainDict — before Dictionary.initial(cfg) has run anywhere in the JVM. Because singleton is a static field, this also happens in tests that fork/reset state or when a classloader boundary creates a second, uninitialized copy of the Dictionary class (e.g. some plugin containers).

Common situations: Upgrading from a classic IK Analyzer version where getSingleton() lazily self-initialized with DefaultConfig to this fork, where initialization is explicit and lazy init was removed; unit tests that construct an IKAnalyzer without the shared TestUtils.initial step; embedding IK in an application server/OSGi bundle where a child classloader loads a fresh Dictionary class after the parent-initialized one; multi-threaded first use racing initialization is safe (initial is synchronized) but zero use before first tokenization is not.

Related errors

AI-assisted analysis of infinilabs/analysis-ik@6d2d70fd1a (2026-08-14). Data as JSON: /api/errors/aba2facb27e123e9. Report an issue: GitHub.