elastic/elasticsearch · error · PolicyValidationException

'basedir_if_relative' may only be used with 'path_setting'

Error message

'basedir_if_relative' may only be used with 'path_setting'

What it means

Thrown when `basedir_if_relative` is present on a files-entitlement entry but `path_setting` is not. `basedir_if_relative` is a modifier of `path_setting` (it tells the parser how to interpret the setting's value if it is relative), so it has no meaning without a `path_setting` to qualify.

Source

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

                    "a files entitlement entry must contain one of " + "[path, relative_path, path_setting]"
                );
            }

            if (modeAsString == null) {
                throw new PolicyValidationException("files entitlement must contain 'mode' for every listed file");
            }
            Mode mode = parseMode(modeAsString);
            Platform platform = null;
            if (platformAsString != null) {
                platform = parsePlatform(platformAsString);
            }

            if (relativeTo != null && relativePathAsString == null) {
                throw new PolicyValidationException("'relative_to' may only be used with 'relative_path'");
            }

            if (settingBaseDirAsString != null && pathSetting == null) {
                throw new PolicyValidationException("'basedir_if_relative' may only be used with 'path_setting'");
            }

            final FileData fileData;
            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");
                }

View on GitHub (pinned to db6a809a66)

Solutions

1. If you intended to resolve a setting-named path against a base dir, switch the entry to use `path_setting` plus `basedir_if_relative`.
2. Otherwise, remove the `basedir_if_relative` field.

Example fix

// before
{ "relative_path": "logs", "relative_to": "home", "basedir_if_relative": "data", "mode": "read" }

// after
{ "relative_path": "logs", "relative_to": "home", "mode": "read" }

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

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

When it happens

Trigger: An entry sets `basedir_if_relative` together with `path` or `relative_path`, or with no path designator at all.

Common situations: Author confuses `basedir_if_relative` with `relative_to`; leftover field after switching from `path_setting` to `path`; misunderstanding the role of the field.

Related errors

• invalid relative directory: {}, valid values: [config, data,
• a files entitlement entry must contain one of [path, relativ
• 'relative_to' may only be used with 'relative_path'
• files entitlement with a 'relative_path' must specify 'relat
• 'relative_path' [{}] must be relative

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