dromara/Sa-Token · error · NotImplException

10003

10003

Error message

未实现具体的 json 转换器

What it means

NotImplException (code 10003) thrown by SaJsonTemplateDefaultImpl.objectToJson(). Sa-Token core ships only this do-nothing default JSON template; actual serialization is provided by integration jars (sa-token-json-jackson, sa-token-json-gson, sa-token-json-fastjson, etc.). Hitting it means no real JSON converter was injected, so any framework feature that serializes to JSON (e.g. storing objects in session, sa-token's own JSON persistence) fails.

Source

Thrown at sa-token-core/src/main/java/cn/dev33/satoken/json/SaJsonTemplateDefaultImpl.java:37

import cn.dev33.satoken.exception.NotImplException;

import java.util.Map;

/**
 * JSON 转换器，默认实现类
 *
 * <p> 如果代码断点走到了此默认实现类，说明框架没有注入有效的 JSON 转换器，需要开发者自行实现并注入 </p>
 *
 * @author click33
 * @since 1.30.0
 */
public class SaJsonTemplateDefaultImpl implements SaJsonTemplate {

	public static final String ERROR_MESSAGE = "未实现具体的 json 转换器";

	@Override
	public String objectToJson(Object obj) {
		throw new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);
	}

	@Override
	public Object jsonToObject(String jsonStr) {
		throw new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);
	}

	@Override
	public <T> T jsonToObject(String jsonStr, Class<T> type) {
		throw new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);
	}

	@Override
	public Map<String, Object> jsonToMap(String jsonStr) {
		throw new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);
	}
	
}

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. Add a JSON integration dependency, e.g. <dependency><groupId>cn.dev33</groupId><artifactId>sa-token-json-jackson</artifactId><version>${sa-token.version}</version></dependency> (or gson/fastjson2 variant)
2. If you intentionally have no integration jar, implement SaJsonTemplate yourself and inject: SaManager.setSaJsonTemplate(new MyJsonTemplate()) early at startup
3. Verify only one sa-token-json-* jar is on the classpath and its version matches the core version

Example fix

// before: only sa-token-core on classpath
// SaManager.getSaJsonTemplate().objectToJson(obj) -> NotImplException 10003

// after (pom.xml)
<dependency>
  <groupId>cn.dev33</groupId>
  <artifactId>sa-token-json-jackson</artifactId>
  <version>1.44.0</version>
</dependency>

if (SaManager.getSaJsonTemplate() instanceof SaJsonTemplateDefaultImpl) {
    // no real JSON converter injected; add sa-token-json-* dependency before using JSON features
}

boolean hasRealJsonTemplate() {
    return !(SaManager.getSaJsonTemplate() instanceof cn.dev33.satoken.json.SaJsonTemplateDefaultImpl);
}

try {
    SaManager.getSaJsonTemplate().objectToJson(obj);
} catch (NotImplException e) {
    if (e.getCode() == SaErrorCode.CODE_10003) { /* inject a SaJsonTemplate and retry once */ }
    throw e;
}

When it happens

Trigger: SaManager.getSaJsonTemplate() returns the default impl and application code — or sa-token internals — calls objectToJson(obj). Typical when the project depends on sa-token-core alone, or the JSON integration jar was excluded, and the plugin/SPI loader never registered a real SaJsonTemplate.

Common situations: Using sa-token-core without any sa-token-json-* dependency; excluding the json integration via Maven exclusions while pulling sa-token-spring-boot-starter transitively; a custom SaJsonTemplate registered after first use; classpath conflicts where the SPI file for the json plugin is missing.

Related errors

• 10004
• 10002
• 10002
• 12002
• 12003

AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14). Data as JSON: /api/errors/60554acbd5666934. Report an issue: GitHub.