elastic/elasticsearch · critical · IllegalStateException

user.home system property is required

Error message

user.home system property is required

What it means

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.

Source

Thrown at libs/entitlement/src/main/java/org/elasticsearch/entitlement/bootstrap/EntitlementBootstrap.java:125

        EntitlementInitialization.initializeArgs = new EntitlementInitialization.InitializeArgs(
            pathLookup,
            suppressFailureLogPackages,
            policyChecker,
            instrumentationRegistry
        );
        registerEntitlementRules(instrumentationRegistry);
        exportInitializationToAgent();
        loadAgent(findAgentJar(), EntitlementInitialization.class.getName());

        if (EntitlementInitialization.getError() != null) {
            throw EntitlementInitialization.getError();
        }
    }

    private static Path getUserHome() {
        String userHome = System.getProperty("user.home");
        if (userHome == null) {
            throw new IllegalStateException("user.home system property is required");
        }
        return PathUtils.get(userHome);
    }

    @SuppressForbidden(reason = "The VirtualMachine API is the only way to attach a java agent dynamically")
    static void loadAgent(String agentPath, String entitlementInitializationClassName) {
        long startMillis = System.currentTimeMillis();
        try {
            VirtualMachine vm = VirtualMachine.attach(Long.toString(ProcessHandle.current().pid()));
            long attachedMillis = System.currentTimeMillis();
            try {
                vm.loadAgent(agentPath, entitlementInitializationClassName);
            } finally {
                vm.detach();
            }
            long doneMillis = System.currentTimeMillis();
            logger.info(
                "Entitlement agent attached in [{}ms] (attach=[{}ms], loadAgent+detach=[{}ms])",

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure the JVM is launched normally so 'user.home' is populated from the OS environment.
2. If you intentionally strip system properties, explicitly set -Duser.home=<dir> in the launch command.
3. Check the launcher script or container image for any code that clears system properties.

Example fix

// before: -Duser.home removed or cleared
java -Duser.home= ... -jar es.jar

// after: set a real home
java -Duser.home=/usr/share/elasticsearch ... -jar es.jar

// Before bootstrap, assert user.home is set
String home = System.getProperty("user.home");
if (home == null || home.isBlank()) {
  throw new IllegalStateException("user.home must be set; pass -Duser.home=<dir>");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• CONFIG
• Directory for entitlement jar does not exist: {}
• Expected one jar in {}; found {}
• Invalid qualifier: ${qualifier}
• build.snapshot was set to [${buildSnapshotSystemProperty}] b

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/b818c6c53983dd69. Report an issue: GitHub.