elastic/elasticsearch · error · IllegalStateException

An internal error occurred attempting to define the script [

Error message

An internal error occurred attempting to define the script [{}].

What it means

Compiler.compile wraps any Exception thrown while defining the generated Painless script class (loader.defineScript) or while injecting static constants into it, and rethrows as an IllegalStateException tagged with the script name. This is explicitly a catch-all for internal failures — classloader issues, verification errors, or constant-injection type mismatches — surfaced to the user as 'internal' to signal the cause is not in the script text itself.

Source

Thrown at modules/lang-painless/src/main/java/org/elasticsearch/painless/Compiler.java:216

        new DefaultStringConcatenationOptimizationPhase().visitClass(classNode, null);
        new DefaultConstantFoldingOptimizationPhase().visitClass(classNode, null);
        new DefaultConstantListOptimizationPhase(scriptScope).visitClass(classNode, null);
        new DefaultEqualityMethodOptimizationPhase(scriptScope).visitClass(classNode, null);
        new DefaultStaticConstantExtractionPhase().visitClass(classNode, scriptScope);
        new DefaultIRTreeToASMBytesPhase().visitScript(classNode);
        byte[] bytes = classNode.getBytes();

        try {
            Class<? extends PainlessScript> clazz = loader.defineScript(CLASS_NAME, bytes);

            for (Map.Entry<String, Object> staticConstant : scriptScope.getStaticConstants().entrySet()) {
                clazz.getField(staticConstant.getKey()).set(null, staticConstant.getValue());
            }

            return scriptScope;
        } catch (Exception exception) {
            // Catch everything to let the user know this is something caused internally.
            throw new IllegalStateException("An internal error occurred attempting to define the script [" + name + "].", exception);
        }
    }

    /**
     * Runs the two-pass compiler to generate a Painless script.  (Used by the debugger.)
     * @param source The source code for the script.
     * @param settings The CompilerSettings to be used during the compilation.
     * @return The bytes for compilation.
     */
    byte[] compile(String name, String source, CompilerSettings settings, Printer debugStream) {
        String scriptName = Location.computeSourceName(name);
        ScriptClassInfo scriptClassInfo = new ScriptClassInfo(painlessLookup, scriptClass);
        SClass root = Walker.buildPainlessTree(scriptName, source, settings);
        ScriptScope scriptScope = new ScriptScope(painlessLookup, settings, scriptClassInfo, scriptName, source, root.getIdentifier() + 1);
        new PainlessSemanticHeaderPhase().visitClass(root, scriptScope);
        new PainlessSemanticAnalysisPhase().visitClass(root, scriptScope);
        new PainlessUserTreeToIRTreePhase().visitClass(root, scriptScope);
        ClassNode classNode = (ClassNode) scriptScope.getDecoration(root, IRNodeDecoration.class).irNode();

View on GitHub (pinned to db6a809a66)

Solutions

Read the wrapped 'exception' cause in the stack trace — it identifies the real failure (e.g. LinkageError, ClassNotFoundException, access exception).
If the cause is an access/entitlement failure, grant the script engine the needed runtime capability or run on a standard distribution.
Restart the node to clear a potentially corrupted classloader state, then recompile.
Simplify the script to a no-op and re-add sections to find which construct produces an uncompilable bytecode shape.
Ensure consistent Elasticsearch/JVM versions across nodes; mixed versions can produce verification errors.

Defensive patterns

Strategy: try-catch

Try / catch

//try { scriptService.compile(...); } catch (IllegalStateException e) {
//   if (e.getMessage().startsWith("An internal error occurred attempting to define the script")) {
//     // Inspect e.getCause() for the real failure (LinkageError, access, etc.)
//     log.error("Painless internal compile failure", e.getCause());
//     // Retry on a fresh classloader state, or surface to ops
//   } else throw e;
//}

Prevention

Always inspect the wrapped cause rather than the top-level message.
Keep all nodes on identical Elasticsearch and JVM versions.
Avoid custom classloader tricks around the script engine.
Reproduce with a minimal script to isolate bytecode-shape issues.

When it happens

Trigger: Compiling a Painless script that is syntactically valid but whose generated bytecode cannot be defined: classloader constraints, a SecurityManager/entitlement blocking defineClass, a corrupted jar/module path, or a static constant whose type cannot be assigned to the generated field. Observed during first execution of a new or cached script.

Common situations: Custom plugin injecting scripts via a non-standard classloader. Module/entitlement changes that block dynamic class definition. JVM/version incompatibility after upgrading the JDK. Concurrent script compilation hitting a classloader race. Mismatched painless API jars on the classpath.

Related errors

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