alibaba/spring-cloud-alibaba · error · IllegalArgumentException

[Sentinel Starter] DataSource {} file cannot be null

Error message

[Sentinel Starter] DataSource {} file cannot be null

What it means

Thrown by FileDataSourceProperties.preCheck during Sentinel datasource initialization when the file field is null. The file field is @Nullable with a @NotEmpty validation annotation but no default value. preCheck calls super.preCheck first, then checks if file is null. The dataSourceName in the message identifies which datasource entry in spring.cloud.sentinel.datasource triggered the error.

Source

Thrown at spring-cloud-alibaba-starters/spring-cloud-alibaba-sentinel-datasource/src/main/java/com/alibaba/cloud/sentinel/datasource/config/FileDataSourceProperties.java:86

	public void setRecommendRefreshMs(long recommendRefreshMs) {
		this.recommendRefreshMs = recommendRefreshMs;
	}

	public int getBufSize() {
		return bufSize;
	}

	public void setBufSize(int bufSize) {
		this.bufSize = bufSize;
	}

	@Override
	public void preCheck(String dataSourceName) {
		super.preCheck(dataSourceName);
		String file = this.getFile();
		if (file == null) {
			throw new IllegalArgumentException("[Sentinel Starter] DataSource " + dataSourceName
					+ " file cannot be null");
		}
		try {
			this.setFile(
					ResourceUtils.getFile(StringUtils.trimAllWhitespace(file))
							.getAbsolutePath());
		}
		catch (IOException e) {
			throw new RuntimeException("[Sentinel Starter] DataSource " + dataSourceName
					+ " handle file [" + file + "] error: " + e.getMessage(),
					e);
		}

	}

}

View on GitHub (pinned to 115d590110)

Solutions

1. Add spring.cloud.sentinel.datasource.<name>.file.file=<path-to-rules-file> to your configuration.
2. Ensure the file property is set to a valid file path or Spring resource location (e.g., classpath:sentinel-rules.json or file:/etc/app/rules.json).
3. If using a placeholder, ensure the environment variable is set and non-empty.

Example fix

# before (broken — file path missing)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          file:
            charset: utf-8

# after (fixed)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          file:
            file: classpath:sentinel-rules.json
            charset: utf-8

// Ensure the file property is set for file-type Sentinel datasources
String filePath = props.getFile().getFile();
if (!StringUtils.hasText(filePath)) {
    throw new IllegalArgumentException(
        "Sentinel file datasource requires a non-empty 'file' property");
}

When it happens

Trigger: Configuring a Sentinel datasource of type 'file' (spring.cloud.sentinel.datasource.<name>.file) without specifying the file property. Since the field has no default, any file-type datasource that omits the file path hits this check.

Common situations: 1) Developer declares spring.cloud.sentinel.datasource.ds1.file but forgets the nested 'file' property. 2) Configuration uses a placeholder like ${FILE_PATH} that resolves to empty or is not set in the environment. 3) Copy-paste from a template that had the file path as a TODO.

Related errors

• ConsulDataSource server-host is empty
• ConsulDataSource ruleKey can not be empty
• RedisDataSource ruleKey can not be empty
• RedisDataSource channel can not be empty
• RedisDataSource sentinel model，masterId can not be empty

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