{"record":{"id":"b818c6c53983dd69","repo":"elastic/elasticsearch","slug":"user-home-system-property-is-required","errorCode":null,"errorMessage":"user.home system property is required","messagePattern":"user\\.home system property is required","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java","lineNumber":125,"sourceCode":"        EntitlementInitialization.initializeArgs = new EntitlementInitialization.InitializeArgs(\n            pathLookup,\n            suppressFailureLogPackages,\n            policyChecker,\n            instrumentationRegistry\n        );\n        registerEntitlementRules(instrumentationRegistry);\n        exportInitializationToAgent();\n        loadAgent(findAgentJar(), EntitlementInitialization.class.getName());\n\n        if (EntitlementInitialization.getError() != null) {\n            throw EntitlementInitialization.getError();\n        }\n    }\n\n    private static Path getUserHome() {\n        String userHome = System.getProperty(\"user.home\");\n        if (userHome == null) {\n            throw new IllegalStateException(\"user.home system property is required\");\n        }\n        return PathUtils.get(userHome);\n    }\n\n    @SuppressForbidden(reason = \"The VirtualMachine API is the only way to attach a java agent dynamically\")\n    static void loadAgent(String agentPath, String entitlementInitializationClassName) {\n        long startMillis = System.currentTimeMillis();\n        try {\n            VirtualMachine vm = VirtualMachine.attach(Long.toString(ProcessHandle.current().pid()));\n            long attachedMillis = System.currentTimeMillis();\n            try {\n                vm.loadAgent(agentPath, entitlementInitializationClassName);\n            } finally {\n                vm.detach();\n            }\n            long doneMillis = System.currentTimeMillis();\n            logger.info(\n                \"Entitlement agent attached in [{}ms] (attach=[{}ms], loadAgent+detach=[{}ms])\",","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java#L107-L143","documentation":"Thrown by EntitlementBootstrap.getUserHome when the JVM system property 'user.home' is null. The entitlement bootstrap needs the user's home directory to locate policy/config files; a null user.home means the JVM was launched in a severely stripped environment. This is a fatal configuration error, not a normal runtime condition.","triggerScenarios":"System.getProperty(\"user.home\") returns null. This happens when the JVM is started with -Duser.home explicitly cleared or in a container/embedded harness that strips the standard system property.","commonSituations":"A test harness or custom launcher that calls System.getProperties().clear(); running under a security-restricted harness; an embedded JVM integration that does not populate standard properties; explicitly passing -Duser.home= (empty) is not null but an unrelated misconfiguration.","solutions":["Ensure the JVM is launched normally so 'user.home' is populated from the OS environment.","If you intentionally strip system properties, explicitly set -Duser.home=<dir> in the launch command.","Check the launcher script or container image for any code that clears system properties."],"exampleFix":"// before: -Duser.home removed or cleared\njava -Duser.home= ... -jar es.jar\n\n// after: set a real home\njava -Duser.home=/usr/share/elasticsearch ... -jar es.jar","handlingStrategy":"validation","validationCode":"// Before bootstrap, assert user.home is set\nString home = System.getProperty(\"user.home\");\nif (home == null || home.isBlank()) {\n  throw new IllegalStateException(\"user.home must be set; pass -Duser.home=<dir>\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Launch ES with a normal JVM so standard system properties are populated.","Audit custom launchers/scripts for any System.getProperties().clear() call."],"tags":["entitlement","system-property","startup","environment"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}