How to fix ScriptException: compile error in Elasticsearch

ElasticsearchINTERMEDIATEMEDIUMUpdated Dec 18, 2025· 120 views

This error occurs when Elasticsearch cannot compile a Painless script due to syntax errors, invalid tokens, or other compilation issues in your script code.

Quick fix

Fixes ScriptException: compile error

{
  "error": {
    "type": "script_exception",
    "reason": "compile error",
    "script_stack": [
      "... if (ctx.field == 'value') {",
      "                    ^---- HERE"
    ],
    "caused_by": {
      "type": "illegal_argument_exception",
      "reason": "invalid sequence of tokens near ['value']."
    }
  }
}
  1. Review the script_stack error location
  2. Check for common syntax errors
  3. Use Debug.explain() to inspect available fields
  4. Test script syntax in small increments
elasticsearch — error
{
  "error": {
    "type": "script_exception",
    "reason": "compile error",
    "script_stack": [
      "... if (ctx.field == 'value') {",
      "                    ^---- HERE"
    ],
    "caused_by": {
      "type": "illegal_argument_exception",
      "reason": "invalid sequence of tokens near ['value']."
    }
  }
}
ScriptException: compile error

What this error means

The "ScriptException: compile error" indicates that Elasticsearch's Painless scripting engine encountered a problem while attempting to compile your script before execution. Painless is Elasticsearch's built-in scripting language used in queries, aggregations, updates, and ingest pipelines. When you submit a script to Elasticsearch, it first compiles it into bytecode before running it. If the script contains syntax errors, invalid operators, type mismatches, or other compilation issues, Elasticsearch rejects the request with a 400 (Bad Request) status and returns this ScriptException. The error response typically includes a "script_stack" field that shows where the error occurred, marked with "^---- HERE" to pinpoint the exact location of the problem in your script code.

Typical symptoms

  • Query or aggregation requests fail with HTTP 400 status
  • Error message shows "ScriptException: compile error" in the response
  • Script_stack field in response indicates "unexpected token" or syntax issues
  • Ingest pipeline fails to process documents
  • Update by query operations fail during script compilation
  • Error includes pointer (^---- HERE) showing exact error location

Common causes

  1. Syntax errors in Painless script (missing semicolons, braces, or parentheses)
  2. Using invalid operators or incorrect operator syntax
  3. Type mismatches between variables and operations
  4. Referencing undefined variables or fields
  5. Missing closing braces or brackets in nested structures
  6. Using reserved keywords incorrectly
  7. Invalid sequence of tokens in conditional statements
  8. Attempting to use features from other scripting languages (Groovy, JavaScript)
  9. Incorrect field access syntax in document context

How to fix "ScriptException: compile error"

1Review the script_stack error location

Examine the error response to find the exact location of the compile error:

json
{
  "error": {
    "type": "script_exception",
    "reason": "compile error",
    "script_stack": [
      "... if (ctx.field == 'value') {",
      "                    ^---- HERE"
    ],
    "caused_by": {
      "type": "illegal_argument_exception",
      "reason": "invalid sequence of tokens near ['value']."
    }
  }
}

The "^---- HERE" marker shows exactly where the compilation failed.

2Check for common syntax errors

Verify your script follows Painless syntax rules:

Missing semicolons:

javascript
// Wrong
def x = 1
def y = 2

// Correct
def x = 1;
def y = 2;

Missing braces:

javascript
// Wrong
if (ctx.status == 'active')
  ctx.count++

// Correct
if (ctx.status == 'active') {
  ctx.count++;
}

String comparison:

javascript
// Wrong (single equals in condition)
if (ctx.field = 'value') { }

// Correct (double equals)
if (ctx.field == 'value') { }
3Use Debug.explain() to inspect available fields

When working with document context, use Debug.explain() to see what's available:

json
POST /my-index/_explain/1
{
  "query": {
    "script_score": {
      "query": { "match_all": {} },
      "script": {
        "source": "Debug.explain(doc)"
      }
    }
  }
}

This shows the structure and types of fields you can access in your script.

4Test script syntax in small increments

Build your script gradually to isolate the problem:

json
POST /_scripts/painless/_execute
{
  "script": {
    "source": "return 1 + 1;"
  }
}

Add complexity step by step:

json
POST /_scripts/painless/_execute
{
  "script": {
    "source": """
      def x = params.value;
      if (x > 10) {
        return x * 2;
      }
      return x;
    """,
    "params": {
      "value": 15
    }
  }
}
5Review Painless documentation for correct syntax

Painless has specific syntax requirements that differ from other languages:

Field access:

javascript
// Use doc['field'].value for doc values
doc['price'].value * 1.1

// Use params._source for source fields
params._source.nested.field

Safe navigation:

javascript
// Handle missing fields
doc.containsKey('field') ? doc['field'].value : 0

Ternary operators:

javascript
// Correct ternary syntax
def result = condition ? value1 : value2;

Refer to the official Painless scripting guide for complete syntax rules.

6Check for reserved keyword conflicts

Avoid using reserved Painless keywords as variable names:

javascript
// Wrong - 'in' is a reserved keyword
def in = 5;

// Correct - use different name
def input = 5;

Common reserved words: if, else, for, while, return, def, true, false, null, in, instanceof.

Advanced notes

Compilation Caching:
Elasticsearch caches compiled scripts to improve performance. The default limit is 100 cached scripts with a maximum size of 1000. Scripts are compiled on first use and evicted using LRU (Least Recently Used) policy. To see cache statistics:

bash
GET /_nodes/stats/script

Dynamic Script Compilation Limits:
By default, Elasticsearch allows 150 script compilations per 5 minutes (75/5min for Painless specifically) to prevent circuit breaker exceptions. If you frequently compile unique scripts, consider using stored scripts or parameterized scripts instead:

json
PUT _scripts/my-script
{
  "script": {
    "lang": "painless",
    "source": "doc['field'].value * params.multiplier"
  }
}

Then reference it by ID:

json
GET /my-index/_search
{
  "query": {
    "script_score": {
      "query": { "match_all": {} },
      "script": {
        "id": "my-script",
        "params": {
          "multiplier": 2
        }
      }
    }
  }
}

Type Strictness:
Painless enforces strong typing. All variables must have compatible types for operations. Use explicit casting when needed:

javascript
// Cast to specific type
int count = (int) doc['count'].value;
double price = (double) doc['price'].value;

Debugging Strategy:
When facing complex compilation errors, extract the script to a text editor with Java syntax highlighting. Painless syntax closely resembles Java, so many IDEs can help identify syntax issues before you deploy to Elasticsearch.

Frequently asked questions

What does "ScriptException: compile error" mean?
The "ScriptException: compile error" indicates that Elasticsearch's Painless scripting engine encountered a problem while attempting to compile your script before execution. Painless is Elasticsearch's built-in scripting language used in queries, aggregations, updates, and ingest pipelines. When you submit a script to Elasticsearch, it first compiles it into bytecode before running it.
How do I fix "ScriptException: compile error"?
This error occurs when Elasticsearch cannot compile a Painless script due to syntax errors, invalid tokens, or other compilation issues in your script code.
What causes "ScriptException: compile error"?
Syntax errors in Painless script (missing semicolons, braces, or parentheses) Using invalid operators or incorrect operator syntax Type mismatches between variables and operations
Is the "ScriptException: compile error" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading