alibaba/spring-cloud-alibaba · error · RuntimeException

[Sentinel Starter] DataSource {} handle file [{}] error: {}

Error message

[Sentinel Starter] DataSource {} handle file [{}] error: {}

What it means

Thrown by FileDataSourceProperties.preCheck when ResourceUtils.getFile() fails to resolve the configured file path to a java.io.File, throwing an IOException. This RuntimeException wraps the original IOException with context including the datasource name and the problematic path. The error occurs during preCheck, which runs after the null check passes, attempting to convert the path (e.g., a classpath: or file: resource string) to an absolute filesystem path.

Source

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

	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. Ensure the file path resolves to a real filesystem file — use an absolute file: path or a classpath resource that exists on disk (not inside a JAR).
2. Verify the file exists at the resolved path: check with ls or similar.
3. If the resource is inside a JAR, copy it to the filesystem at startup or use a different datasource type (e.g., Nacos, Apollo) that does not require filesystem access.
4. Check for typos, extra whitespace, or incorrect directory separators in the path.

Example fix

# before (broken — resource inside JAR)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          file:
            file: classpath:sentinel-rules.json  # inside JAR, getFile() fails

# after (fixed — absolute filesystem path)
spring:
  cloud:
    sentinel:
      datasource:
        ds1:
          file:
            file: file:/opt/app/config/sentinel-rules.json

// Pre-validate that the resource resolves to a filesystem file
import org.springframework.util.ResourceUtils;

String fileProp = props.getFile().getFile();
try {
    File resolved = ResourceUtils.getFile(fileProp.trim());
    if (!resolved.exists()) {
        throw new IllegalStateException("File not found: " + resolved.getAbsolutePath());
    }
} catch (IOException e) {
    throw new IllegalStateException("Cannot resolve file path: " + fileProp, e);
}

// In a custom configuration or initializer:
try {
    File resolved = ResourceUtils.getFile(StringUtils.trimAllWhitespace(filePath));
    // proceed
} catch (IOException e) {
    log.error("Cannot resolve Sentinel file datasource path: {}", filePath, e);
    // fall back to a known-good path or fail fast with actionable message
    throw new IllegalStateException("Resolve file datasource path first: " + filePath, e);
}

When it happens

Trigger: Configuring a file-type Sentinel datasource with a file property value that ResourceUtils.getFile() cannot resolve. This includes: classpath resources that are inside a JAR (not on the filesystem), non-existent file: paths, malformed resource URIs, or paths with syntax errors. StringUtils.trimAllWhitespace is applied first, but the resolved path must point to an actual filesystem file.

Common situations: 1) Using classpath:sentinel-rules.json when the resource is packaged inside a JAR and cannot be resolved as a filesystem File. 2) File path references a location that does not exist on the deployed machine. 3) The path contains a typo or wrong directory separator. 4) Running in a container where the mounted volume path differs from the configured path.

Related errors

• [Sentinel Starter] DataSource {} file cannot be null
• ConsulDataSource server-host is empty
• ConsulDataSource ruleKey can not be empty
• RedisDataSource ruleKey can not be empty
• RedisDataSource channel can not be empty

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