Elasticsearch Mapper Parsing Exception: Fix Fast

Deploys turn red on Friday afternoon: thousands of mapper_parsing_exception errors, documents rejected, and the events index missing 12% of traffic. The new app version sends latency as an object with value and unit; the old mapping expects a long. Both versions write to the same index, and Elasticsearch refuses to store the contradiction.

Mapping conflicts are schema wars with a simple rule: one field, one type, per index, forever. Dynamic mapping crowns the first document's shape as law, and every later producer with a different shape gets rejected. The error message names the field and both types — the diagnosis is printed on the rejection.

This guide decodes the error, finds every producer sending the wrong shape, and fixes it with explicit mappings plus a zero-downtime reindex. You'll learn strictness levels, multi-field escapes, and template discipline that stops two app versions from ever sharing one schema again. Copy the field name from your error message now: every section below keys off that one string and its two types.

Decoding the Error: Field, Type, and Offending Value

The error message is unusually honest. It names the field, the declared type it expected, and previews the offending value — long expected, object received. No archaeology needed: two shapes, one field, stated plainly.

Confirm against the mapping. GET the index mapping and read the field's declared type plus its context: dynamic or strict, coerced or not, multi-fields present or absent. The mapping plus the error preview is the entire case file — declared law versus arriving reality.

Classify the war before sentencing. First-writer-wins means dynamic mapping guessed from whoever arrived first. Mixed producers means services send different shapes concurrently. Version collision means deploys flip the winner. Strict rejection means the mapping is fine and the producer is wrong. Each class ends differently, so name yours first.

Sibling errors share the same root mechanics. number_format_exception means a text value hit a numeric field — same war, different types. illegal_argument_exception on dates means the format fell outside the declared patterns. strict_dynamic_mapping_exception means a strict index met an undeclared field — the mapping is fine and the producer added something new. Read each variant the same way: declared type versus arriving value, named plainly in the message. The fix family never changes: explicit mappings, normalized producers, separated versions. Learn one error deeply and its siblings come free.

# The rejection names field + expected type — read it literally
# mapper_parsing_exception: failed to parse field [latency] of type [long]
#   in document with id 'evt-99182'. Preview of field's value: '{value=184, unit=ms}'

# Confirm the declared type
GET /events-2026.09/_mapping
# mappings.properties.latency.type == "long"  -> war: long vs object

Dynamic Mapping: How First Writers Become Lawmakers

Dynamic mapping infers types from first-seen JSON: strings become text with keyword sub-fields, whole numbers become long, decimals become float, ISO strings become date. Sensible per document, hazardous per index — the first writer's accident becomes every writer's law, permanently.

Strictness levels set the posture. True dynamic guesses and grows; runtime keeps new fields queryable without indexing them; strict rejects unknown fields outright — loud, safe, demanding a schema process. False ignores unknowns silently, the worst option: data vanishes without errors.

Production posture is explicit templates for shared fields with strict or guarded dynamic for the exploratory remainder. Declare every field two teams share; let true dynamic cover only genuinely unknown territory. The template is the schema review meeting, enforced by the cluster.

Date and numeric variance have standard escapes. Declare dates with multiple formats (strict_date_optional_time||epoch_millis) so ISO strings and millisecond epochs coexist legally. Numeric coercion converts quoted numbers transparently while rejecting true text — enable it per index while producers converge on bare numbers. Booleans accept true/false strings under coercion too. These escapes absorb honest variance without hiding gross shape changes: an object arriving for a long still fails loudly, as it should. Forgive formats, never structures.

# Template declaring shared fields before any document arrives
PUT /_index_template/events_template
{
  "index_patterns": ["events-*"],
  "template": {
    "settings": { "index.mapping.coerce": false },
    "mappings": {
      "dynamic": "strict",
      "properties": {
        "latency": { "type": "long" },
        "latency_detail": { "type": "object",
          "properties": { "value": { "type": "long" }, "unit": { "type": "keyword" } } },
        "message": { "type": "text", "fields": { "keyword": { "type": "keyword" } } }
      }
    }
  }
}

Reindex: the Only Real Type Change

Live type changes are impossible by design — Lucene segments encode one type per field, and rewriting history segment-by-segment isn't an update, it's a rebuild. The update-mapping API adds fields but never converts them. Accept this and the fix becomes obvious: build the correct index beside the old one.

The reindex path is mechanical. Create the new index with corrected mappings, run _reindex (sliced for speed on large indices), and reshape values en route with a painless script where shapes changed — splitting old longs into value-plus-unit objects, parsing date strings into ISO. Then verify: document counts match, spot-checked values convert, and previously rejected documents index cleanly against the new mapping.

Cut over with aliases for zero downtime and instant rollback. Point the alias at the new index atomically, watch rejection rates for an hour, and keep the old index through a retention window. Rollback is one alias call — the safety net that makes Friday-afternoon schema work survivable.

Size the operation before running it: source document count times average size sets the time budget, and slices matching your data-node count parallelize the copy. Throttle with requests_per_second when the cluster serves live traffic, and run with wait_for_completion=false plus the task API so a dropped terminal never kills visibility. Reindex never modifies the source, so reruns are safe — fix the script and relaunch rather than patching a half-built destination. A calm, throttled, observable reindex beats a fast one that trips breakers halfway through.

# Reshape history en route: old longs become value-plus-unit objects
POST /_reindex?wait_for_completion=false
{
  "source": { "index": "events-2026.09", "slice": { "id": 0, "max": 4 } },
  "dest": { "index": "events_v2" },
  "script": {
    "source": "if (ctx._source.latency instanceof Long) { ctx._source.latency_detail = ['value': ctx._source.latency, 'unit': 'ms'] }"
  }
}

# Atomic cutover (rollback swaps the two actions)
POST /_aliases
{ "actions": [
  { "remove": { "index": "events-2026.09", "alias": "events" } },
  { "add": { "index": "events_v2", "alias": "events" } } ] }

Multi-Fields, Coercion, and Other Escape Hatches

Mixed shapes don't always need war — several escapes absorb variance legally. Multi-fields index one JSON value under two types: text for search plus keyword for sort and aggs, or long with a keyword sub-field for quoted numbers. Coerce converts numeric strings to numbers (and back) at index time, forgiving producer inconsistency without hiding it entirely.

Choose by variance source. Producer sloppiness (quoted vs bare numbers) yields to coerce plus normalization at the edge. Genuine dual needs (search text, aggregate keyword) yield to multi-fields declared up front. True type collision (object vs long across versions) yields only to separation — no mapping trick holds both shapes in one field.

Use ignore_malformed sparingly and visibly. Per-field with rejection-count monitoring, it keeps pipelines flowing during producer fixes. Global and unmonitored, it's a data-loss machine with no alarms — the audit discovery nobody wants.

Runtime fields rescue read paths without reindexing. Define a runtime keyword that parses the messy source field at query time for dashboards that must work today, then reindex properly when the schedule allows. They cost query speed for flexibility — fine for low-traffic admin views, wrong for hot paths. ignore_above on keyword fields truncates monster tokens instead of failing documents, protecting pipelines from pathological inputs. Use these as bridges with expiry dates, not permanent architecture. Every bridge needs a demolition ticket.

# Dual-need field: search the text, aggregate the keyword
PUT /events_v2/_mapping
{ "properties": { "status": {
  "type": "text",
  "fields": { "keyword": { "type": "keyword" } } } } }

# Forgive quoted numbers while producers normalize
PUT /events_v2/_settings
{ "index.mapping.coerce": true }

Keeping Two App Versions From Sharing One Schema

The permanent fix is organizational: one schema version per index family, enforced by routing and tests. Versioned names (events-v2-*) or version-routed data streams isolate shapes so v1 strings and v2 objects never meet. Rollover and retention separate cleanly as a bonus.

Enforce with contract tests. Every producer's event fixtures validate against the template's schema in CI — new shapes fail the build, not the cluster at 5 PM. Schema registries or shared fixture files make the contract concrete across services and languages.

Audit templates quarterly. Fields drift, teams forget, dynamic sections accumulate guesses. A scheduled review comparing template declarations against actual indexed shapes catches the next war while it's still a warning in a test log.

Data streams and composable templates scale the versioning discipline. Data streams route writes to the current backing index while searches span all of them — version upgrades create new backing indices with new mappings transparently. Composable templates separate index patterns, priority ordering, and component pieces so schema pieces compose instead of duplicating. Version bumps become template edits plus rollover, never shared-index wars. Adopt streams for append-only event families; keep classic indices only where update patterns demand them. Modern primitives remove whole incident classes.

Verifying the Cutover: Counts, Spot-Checks, and Rollback

Cutover day is verification day, not celebration day. Watch the _reindex task API while it runs: the failures array names every document the script could not reshape, and each failure is a producer shape you have not handled yet. Compare counts when it finishes — the new index must hold the old count plus every replayed rejection, minus nothing. Spot-check converted documents directly: old longs became value-plus-unit objects, dates normalized to one format, multi-fields populated on both text and keyword sides. Replay the previously rejected documents and confirm zero mapper errors this time.

Prove reads, not just writes. Run your top production queries against the new index and diff result counts with the old: aggregations on converted fields must match, sorts on keyword sub-fields must order identically, date histograms must bucket the same hours. Any mismatch means the shaping script lied somewhere — fix the script, rebuild the index, and re-verify from counts. Swap the alias atomically only after queries agree, then monitor rejection rate and search traffic for a full hour. Keep the old index through one full retention window: rollback stays a single alias call, and disk is cheap compared to lost history.

Record the mapping, the script, and the verification queries next to the template change. The next schema evolution reuses all three, and reindexing stops being frightening the second time because the runbook already exists. Teams that verify this way cut over on Friday afternoons without fear; teams that skip the count check discover missing documents during audits months later.