{"record":{"id":"1e791c1dad81303b","repo":"elastic/elasticsearch","slug":"files-entitlement-with-a-path-setting-must-speci","errorCode":null,"errorMessage":"files entitlement with a 'path_setting' must specify 'basedir_if_relative'","messagePattern":"files entitlement with a 'path_setting' must specify 'basedir_if_relative'","errorType":"validation","errorClass":"PolicyValidationException","httpStatus":null,"severity":"error","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java","lineNumber":294,"sourceCode":"            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                }\n                fileData = FileData.ofPath(path, mode);\n            } else if (pathSetting != null) {\n                if (settingBaseDirAsString == null) {\n                    throw new PolicyValidationException(\"files entitlement with a 'path_setting' must specify 'basedir_if_relative'\");\n                }\n                BaseDir baseDir = parseBaseDir(settingBaseDirAsString);\n                fileData = FileData.ofPathSetting(pathSetting, baseDir, mode);\n            } else {\n                throw new AssertionError(\"File entry validation error\");\n            }\n            filesData.add(fileData.withPlatform(platform).withExclusive(exclusive));\n        }\n        return new FilesEntitlement(filesData);\n    }\n}\n","sourceCodeStart":276,"sourceCodeEnd":306,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/runtime/policy/entitlements/FilesEntitlement.java#L276-L306","documentation":"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.","triggerScenarios":"An entry has `path_setting` but no `basedir_if_relative`, e.g. `{ \"path_setting\": \"my.path.key\", \"mode\": \"read\" }`.","commonSituations":"Author assumes a default base dir; forgot the companion field; template that omitted the line; refactor that renamed or removed `basedir_if_relative`.","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`."],"exampleFix":"// before\n{ \"path_setting\": \"logger.path\", \"mode\": \"read_write\" }\n\n// after\n{ \"path_setting\": \"logger.path\", \"basedir_if_relative\": \"data\", \"mode\": \"read_write\" }","handlingStrategy":"validation","validationCode":"public static void validatePathSettingPairing(Map<String,Object> entry) {\n    if (entry.containsKey(\"path_setting\") && !entry.containsKey(\"basedir_if_relative\")) {\n        throw new IllegalArgumentException(\"path_setting requires basedir_if_relative\");\n    }\n}","typeGuard":"public static boolean pathSettingOk(Map<String,Object> e) {\n    return !e.containsKey(\"path_setting\") || e.containsKey(\"basedir_if_relative\");\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["entitlements","files","policy","validation","paths","settings"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}