{"record":{"id":"9548dd66e0b27504","repo":"elastic/elasticsearch","slug":"basedir-if-relative-may-only-be-used-with-path","errorCode":null,"errorMessage":"'basedir_if_relative' may only be used with 'path_setting'","messagePattern":"'basedir_if_relative' may only be used with 'path_setting'","errorType":"validation","errorClass":"PolicyValidationException","httpStatus":null,"severity":"error","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java","lineNumber":272,"sourceCode":"                    \"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) {\n                Path path = Path.of(pathAsString);\n                if (FileUtils.isAbsolutePath(pathAsString) == false) {\n                    throw new PolicyValidationException(\"'path' [\" + pathAsString + \"] must be absolute\");\n                }","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java#L254-L290","documentation":"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.","triggerScenarios":"An entry sets `basedir_if_relative` together with `path` or `relative_path`, or with no path designator at all.","commonSituations":"Author confuses `basedir_if_relative` with `relative_to`; leftover field after switching from `path_setting` to `path`; misunderstanding the role of the field.","solutions":["If you intended to resolve a setting-named path against a base dir, switch the entry to use `path_setting` plus `basedir_if_relative`.","Otherwise, remove the `basedir_if_relative` field."],"exampleFix":"// before\n{ \"relative_path\": \"logs\", \"relative_to\": \"home\", \"basedir_if_relative\": \"data\", \"mode\": \"read\" }\n\n// after\n{ \"relative_path\": \"logs\", \"relative_to\": \"home\", \"mode\": \"read\" }","handlingStrategy":"validation","validationCode":"public static void validateBasedirPairing(Map<String,Object> entry) {\n    if (entry.containsKey(\"basedir_if_relative\") && !entry.containsKey(\"path_setting\")) {\n        throw new IllegalArgumentException(\"basedir_if_relative requires path_setting\");\n    }\n}","typeGuard":"public static boolean basedirOk(Map<String,Object> e) {\n    return !e.containsKey(\"basedir_if_relative\") || e.containsKey(\"path_setting\");\n}","tryCatchPattern":null,"preventionTips":["Treat basedir_if_relative as a companion of path_setting only.","Add a JSON Schema conditional linking the two fields.","Do not confuse basedir_if_relative with relative_to."],"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"}