alibaba/spring-cloud-alibaba · error · IllegalStateException

file and charset must not be null

Error message

file and charset must not be null

What it means

Thrown by FileRefreshableDataSourceFactoryBean.getObject() when either file or charset is null. This FactoryBean creates a FileRefreshableDataSource that polls a file for Sentinel rule updates. Both file and charset are @Nullable with no default values (note: FileDataSourceProperties has charset defaulting to 'utf-8', but the FactoryBean field itself does not — if wired directly without going through the properties preCheck, the charset can be null). The check fires during Spring bean initialization.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-alibaba-sentinel-datasource/src/main/java/com/alibaba/cloud/sentinel/datasource/factorybean/FileRefreshableDataSourceFactoryBean.java:50

 * @see FileRefreshableDataSource
 */
public class FileRefreshableDataSourceFactoryBean
		implements FactoryBean<FileRefreshableDataSource> {

	private @Nullable String file;

	private @Nullable String charset;

	private long recommendRefreshMs;

	private int bufSize;

	private @Nullable Converter converter;

	@Override
	public FileRefreshableDataSource getObject() throws Exception {
		if (file == null || charset == null) {
			throw new IllegalStateException("file and charset must not be null");
		}
		return new FileRefreshableDataSource(new File(file), converter,
				recommendRefreshMs, bufSize, Charset.forName(charset));
	}

	@Override
	public Class<?> getObjectType() {
		return FileRefreshableDataSource.class;
	}

	public @Nullable String getFile() {
		return file;
	}

	public void setFile(@Nullable String file) {
		this.file = file;
	}

View on GitHub (pinned to 115d590110)

Solutions

1. Ensure both file and charset are set: file should be a valid filesystem path, charset should be a valid charset name (e.g., 'UTF-8').
2. When using spring.cloud.sentinel.datasource config, verify spring.cloud.sentinel.datasource.<name>.file.file and spring.cloud.sentinel.datasource.<name>.file.charset are both set.
3. If constructing the FactoryBean programmatically, call setFile(path) and setCharset('UTF-8') before getObject().

Example fix

// before (programmatic, missing charset)
FileRefreshableDataSourceFactoryBean fb = new FileRefreshableDataSourceFactoryBean();
fb.setFile("/opt/app/sentinel-rules.json");
fb.setConverter(converter);
fb.getObject(); // throws

// after (fixed)
FileRefreshableDataSourceFactoryBean fb = new FileRefreshableDataSourceFactoryBean();
fb.setFile("/opt/app/sentinel-rules.json");
fb.setCharset("UTF-8");
fb.setConverter(converter);
fb.getObject();

// Validate FileRefreshableDataSource FactoryBean properties
FileRefreshableDataSourceFactoryBean fb = new FileRefreshableDataSourceFactoryBean();
if (file == null || charset == null) {
    throw new IllegalStateException(
        "FileRefreshableDataSource requires both 'file' and 'charset'");
}
fb.setFile(file);
fb.setCharset(charset != null ? charset : "UTF-8");
fb.setConverter(converter);
fb.setRecommendRefreshMs(3000L);
fb.setBufSize(1024 * 1024);
fb.getObject();

When it happens

Trigger: Creating a FileRefreshableDataSourceFactoryBean (directly or via Sentinel datasource config) without setting the file path or charset property. When wired through the standard Sentinel auto-configuration, FileDataSourceProperties.preCheck should have caught a null file earlier, but charset could still be null if the FactoryBean is constructed programmatically or if the properties-to-bean binding skips charset.

Common situations: 1) Programmatic FactoryBean creation without calling setFile() or setCharset(). 2) Configuration binding issue where the charset property is not mapped. 3) Custom FactoryBean instantiation in test code that omits required setters.

Related errors

• [Sentinel Starter] DataSource {} file cannot be null
• namespaceName, flowRulesKey, and defaultFlowRuleValue must n
• Invalid redis sentinel property {}
• serverAddr, groupId, and dataId must not be null
• serverAddr and path must not be null

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/f95ced04e660e9fb. Report an issue: GitHub.