elastic/elasticsearch · error · PolicyValidationException

'relative_to' may only be used with 'relative_path'

Error message

'relative_to' may only be used with 'relative_path'

What it means

Thrown when `relative_to` is present on a files-entitlement entry but `relative_path` is not. `relative_to` is a modifier of `relative_path` (it names the base directory the relative path is resolved against), so it is meaningless on its own and is rejected to surface the inconsistency.

Source

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

            }
            int foundKeys = (pathAsString != null ? 1 : 0) + (relativePathAsString != null ? 1 : 0) + (pathSetting != null ? 1 : 0);
            if (foundKeys != 1) {
                throw new PolicyValidationException(
                    "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) {

View on GitHub (pinned to db6a809a66)

Solutions

1. If you intended a path relative to a known base dir, switch the entry to use `relative_path` plus `relative_to`.
2. Otherwise, remove the `relative_to` field.

Example fix

// before
{ "path": "/var/log/es", "relative_to": "home", "mode": "read" }

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

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

public static boolean relativeToOk(Map<String,Object> e) {
    return !e.containsKey("relative_to") || e.containsKey("relative_path");
}

When it happens

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

Common situations: Author intends to anchor an absolute path to a base dir (not supported — use `relative_path`); leftover field from a refactor; misunderstanding that `relative_to` is a companion of `relative_path`, not an independent directive.

Related errors

• invalid relative directory: {}, valid values: [config, data,
• a files entitlement entry must contain one of [path, relativ
• 'basedir_if_relative' may only be used with 'path_setting'
• 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/25dce893bc47a4a0. Report an issue: GitHub.