alibaba/Sentinel · error · IllegalStateException

Empty rule config path, please set the file path in the env:

Error message

Empty rule config path, please set the file path in the env: SENTINEL_RLS_RULE_FILE_PATH

What it means

EnvoyRlsRuleDataSourceService.init() (Sentinel's Envoy Rate Limit Service) reads the rule file path from the environment; if SENTINEL_RLS_RULE_FILE_PATH is blank it throws IllegalStateException telling you to set it. The service then builds a FileRefreshableDataSource on that YAML file, so without a path the RLS server cannot load any rate-limit descriptors.

Source

Thrown at sentinel-cluster/sentinel-cluster-server-envoy-rls/src/main/java/com/alibaba/csp/sentinel/cluster/server/envoy/rls/datasource/EnvoyRlsRuleDataSourceService.java:58

    private ReadableDataSource<String, List<EnvoyRlsRule>> ds;

    public EnvoyRlsRuleDataSourceService() {
        this.yaml = createYamlParser();
    }

    private Yaml createYamlParser() {
        Representer representer = new Representer();
        representer.getPropertyUtils().setSkipMissingProperties(true);
        return new Yaml(representer);
    }

    public synchronized void init() throws Exception {
        if (ds != null) {
            return;
        }
        String configPath = getRuleConfigPath();
        if (StringUtil.isBlank(configPath)) {
            throw new IllegalStateException("Empty rule config path, please set the file path in the env: "
                + SentinelEnvoyRlsConstants.RULE_FILE_PATH_ENV_KEY);
        }

        this.ds = new FileRefreshableDataSource<>(configPath, s -> Arrays.asList(yaml.loadAs(s, EnvoyRlsRule.class)));
        EnvoyRlsRuleManager.register2Property(ds.getProperty());
    }

    public synchronized void onShutdown() {
        if (ds != null) {
            try {
                ds.close();
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }

    private String getRuleConfigPath() {

View on GitHub (pinned to a3f40ba8e9)

Solutions

1. Set the env var to an absolute path of a readable YAML file: SENTINEL_RLS_RULE_FILE_PATH=/etc/envoy/rls/config.yaml
2. In docker: docker run -e SENTINEL_RLS_RULE_FILE_PATH=/app/rls.yaml -v $(pwd)/rls.yaml:/app/rls.yaml ...
3. Verify the file exists and the process has read permission on it
4. Validate the YAML matches the EnvoyRlsRule schema (domain + descriptors) so the next failure doesn't occur

Example fix

# before
docker run sentinel-envoy-rls

# after
docker run -e SENTINEL_RLS_RULE_FILE_PATH=/etc/sentinel/rls.yaml \
  -v $PWD/rls.yaml:/etc/sentinel/rls.yaml sentinel-envoy-rls

String p = System.getenv("SENTINEL_RLS_RULE_FILE_PATH");
if (p == null || p.trim().isEmpty() || !new java.io.File(p).canRead()) {
    throw new IllegalStateException("Configure SENTINEL_RLS_RULE_FILE_PATH to a readable YAML file before start");
}

When it happens

Trigger: Starting the envoy-rls standalone service without the SENTINEL_RLS_RULE_FILE_PATH env var, or with it set to empty/whitespace; running the docker image without mounting/env-passing the variable.

Common situations: Deploying the sentinel-cluster-server-envoy-rls image behind Envoy's rate_limit filter and forgetting the env var; CI runs that don't export the variable; value present but blank string.

Related errors

• Not a valid RLS rule
• Invalid HTTP status code: ${httpStatus}
• Invalid HTTP status code: ${httpStatus}
• The sentinel_default_context can't be permit to defined!
• Consul has not been initialized or error occurred

AI-assisted analysis of alibaba/Sentinel@a3f40ba8e9 (2026-08-14). Data as JSON: /api/errors/44ae5c4e34b8a1b5. Report an issue: GitHub.