elastic/elasticsearch · error · PolicyValidationException

files entitlement with a 'path_setting' must specify 'basedi

Error message

files entitlement with a 'path_setting' must specify 'basedir_if_relative'

What it means

Thrown when `path_setting` is present on a files-entitlement entry but `basedir_if_relative` is missing. A path-setting entry resolves a settings-defined path; the parser must know which base directory to use if the setting's value is relative, so the companion `basedir_if_relative` field is mandatory.

Source

Thrown at libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java:294

            if (relativePathAsString != null) {
                if (relativeTo == null) {
                    throw new PolicyValidationException("files entitlement with a 'relative_path' must specify 'relative_to'");
                }
                BaseDir baseDir = parseBaseDir(relativeTo);
                Path relativePath = Path.of(relativePathAsString);
                if (FileUtils.isAbsolutePath(relativePathAsString)) {
                    throw new PolicyValidationException("'relative_path' [" + relativePathAsString + "] must be relative");
                }
                fileData = FileData.ofRelativePath(relativePath, baseDir, mode);
            } else if (pathAsString != null) {
                Path path = Path.of(pathAsString);
                if (FileUtils.isAbsolutePath(pathAsString) == false) {
                    throw new PolicyValidationException("'path' [" + pathAsString + "] must be absolute");
                }
                fileData = FileData.ofPath(path, mode);
            } else if (pathSetting != null) {
                if (settingBaseDirAsString == null) {
                    throw new PolicyValidationException("files entitlement with a 'path_setting' must specify 'basedir_if_relative'");
                }
                BaseDir baseDir = parseBaseDir(settingBaseDirAsString);
                fileData = FileData.ofPathSetting(pathSetting, baseDir, mode);
            } else {
                throw new AssertionError("File entry validation error");
            }
            filesData.add(fileData.withPlatform(platform).withExclusive(exclusive));
        }
        return new FilesEntitlement(filesData);
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

Add `"basedir_if_relative": "<base>"` where <base> is one of config, data, home (or shared_data/shared_repo for internal modules).
If you actually meant a static path rather than one sourced from settings, switch to `path` (absolute) or `relative_path`+`relative_to`.

Example fix

// before
{ "path_setting": "logger.path", "mode": "read_write" }

// after
{ "path_setting": "logger.path", "basedir_if_relative": "data", "mode": "read_write" }

Defensive patterns

Strategy: validation

Validate before calling

public static void validatePathSettingPairing(Map<String,Object> entry) {
    if (entry.containsKey("path_setting") && !entry.containsKey("basedir_if_relative")) {
        throw new IllegalArgumentException("path_setting requires basedir_if_relative");
    }
}

Type guard

public static boolean pathSettingOk(Map<String,Object> e) {
    return !e.containsKey("path_setting") || e.containsKey("basedir_if_relative");
}

Prevention

Always emit basedir_if_relative alongside path_setting.
If you meant a literal path (not one resolved from settings), use `path` or `relative_path`.
Add a JSON Schema conditional linking the two fields.

When it happens

Trigger: An entry has `path_setting` but no `basedir_if_relative`, e.g. `{ "path_setting": "my.path.key", "mode": "read" }`.

Common situations: Author assumes a default base dir; forgot the companion field; template that omitted the line; refactor that renamed or removed `basedir_if_relative`.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/1e791c1dad81303b. Report an issue: GitHub.