{"record":{"id":"25dce893bc47a4a0","repo":"elastic/elasticsearch","slug":"relative-to-may-only-be-used-with-relative-path","errorCode":null,"errorMessage":"'relative_to' may only be used with 'relative_path'","messagePattern":"'relative_to' may only be used with 'relative_path'","errorType":"validation","errorClass":"PolicyValidationException","httpStatus":null,"severity":"error","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java","lineNumber":268,"sourceCode":"            }\n            int foundKeys = (pathAsString != null ? 1 : 0) + (relativePathAsString != null ? 1 : 0) + (pathSetting != null ? 1 : 0);\n            if (foundKeys != 1) {\n                throw new PolicyValidationException(\n                    \"a files entitlement entry must contain one of \" + \"[path, relative_path, path_setting]\"\n                );\n            }\n\n            if (modeAsString == null) {\n                throw new PolicyValidationException(\"files entitlement must contain 'mode' for every listed file\");\n            }\n            Mode mode = parseMode(modeAsString);\n            Platform platform = null;\n            if (platformAsString != null) {\n                platform = parsePlatform(platformAsString);\n            }\n\n            if (relativeTo != null && relativePathAsString == null) {\n                throw new PolicyValidationException(\"'relative_to' may only be used with 'relative_path'\");\n            }\n\n            if (settingBaseDirAsString != null && pathSetting == null) {\n                throw new PolicyValidationException(\"'basedir_if_relative' may only be used with 'path_setting'\");\n            }\n\n            final FileData fileData;\n            if (relativePathAsString != null) {\n                if (relativeTo == null) {\n                    throw new PolicyValidationException(\"files entitlement with a 'relative_path' must specify 'relative_to'\");\n                }\n                BaseDir baseDir = parseBaseDir(relativeTo);\n                Path relativePath = Path.of(relativePathAsString);\n                if (FileUtils.isAbsolutePath(relativePathAsString)) {\n                    throw new PolicyValidationException(\"'relative_path' [\" + relativePathAsString + \"] must be relative\");\n                }\n                fileData = FileData.ofRelativePath(relativePath, baseDir, mode);\n            } else if (pathAsString != null) {","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java#L250-L286","documentation":"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.","triggerScenarios":"An entry sets `relative_to` together with `path` or `path_setting`, or sets `relative_to` with no path designator at all.","commonSituations":"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.","solutions":["If you intended a path relative to a known base dir, switch the entry to use `relative_path` plus `relative_to`.","Otherwise, remove the `relative_to` field."],"exampleFix":"// before\n{ \"path\": \"/var/log/es\", \"relative_to\": \"home\", \"mode\": \"read\" }\n\n// after\n{ \"relative_path\": \"log/es\", \"relative_to\": \"home\", \"mode\": \"read\" }","handlingStrategy":"validation","validationCode":"public static void validateRelativeToPairing(Map<String,Object> entry) {\n    if (entry.containsKey(\"relative_to\") && !entry.containsKey(\"relative_path\")) {\n        throw new IllegalArgumentException(\"relative_to requires relative_path\");\n    }\n}","typeGuard":"public static boolean relativeToOk(Map<String,Object> e) {\n    return !e.containsKey(\"relative_to\") || e.containsKey(\"relative_path\");\n}","tryCatchPattern":null,"preventionTips":["Treat relative_to as a companion of relative_path; never emit one without the other.","Use a JSON Schema conditional (if/then) tying the two together.","If you meant an absolute path, switch to the `path` field."],"tags":["entitlements","files","policy","validation","paths"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}