How to fix IllegalArgumentException: mapper [field] cannot be changed from type [text] to [keyword] in Elasticsearch

ElasticsearchINTERMEDIATEHIGHUpdated Dec 29, 2025· 228 views

Elasticsearch doesn't allow changing an existing field's type once it's been mapped. You need to create a new index with the correct mapping and reindex your data to fix this error.

Quick fix

Fixes IllegalArgumentException

curl -X GET "localhost:9200/your-index/_mapping/field/your-field-name?pretty"
  1. Check the current mapping of the problematic field
  2. Create a new index with the corrected mapping
  3. Reindex data from the old index to the new index
  4. Verify the reindexed data
elasticsearch — error
curl -X GET "localhost:9200/your-index/_mapping/field/your-field-name?pretty"
IllegalArgumentException: mapper [field] cannot be changed from type [text] to [keyword]

What this error means

This error occurs when you attempt to change the data type of an existing field in an Elasticsearch mapping. For example, trying to change a field from "text" to "keyword" type. Elasticsearch prevents this operation by design because changing field types could invalidate already-indexed data and break existing queries. The mapper is Elasticsearch's component that manages field type definitions, and it strictly enforces type consistency once a field has been indexed.

Typical symptoms

  • Receiving IllegalArgumentException error when updating index mappings
  • Failure during Kibana migrations when field types conflict
  • Unable to modify field types in template mappings
  • Reindexing operations fail due to type mismatches
  • Integration tools like Filebeat or Logstash fail with type conversion errors

Common causes

  1. Attempting to change a field's type directly via PUT mapping API on an existing index
  2. Schema evolution where a field was initially mapped as one type but needs to be another type
  3. Data ingestion tools sending data with unexpected types that conflict with existing mappings
  4. Mapping template updates that conflict with already-indexed documents
  5. Version upgrades where mapping requirements have changed

How to fix "IllegalArgumentException: mapper [field] cannot be changed from type [text] to [keyword]"

1Check the current mapping of the problematic field

First, verify the current field type in your index mapping:

bash
curl -X GET "localhost:9200/your-index/_mapping/field/your-field-name?pretty"

Or for the entire index mapping:

bash
curl -X GET "localhost:9200/your-index/_mapping?pretty"

This will show you what type the field is currently mapped as, confirming the conflict.

2Create a new index with the corrected mapping

Create a new index with the desired field type. First, get the current mapping and modify the problematic field:

bash
curl -X PUT "localhost:9200/your-index-v2" -H "Content-Type: application/json" -d '{
  "mappings": {
    "properties": {
      "your-field-name": {
        "type": "keyword"
      },
      "other-field": {
        "type": "text"
      }
    }
  }
}'

Replace "your-index-v2" with your new index name, and ensure all fields are defined with their correct types. Copy the full mapping from the old index and change only the fields that need type corrections.

3Reindex data from the old index to the new index

Use Elasticsearch's Reindex API to copy all data from the old index to the new one, applying the new mapping:

bash
curl -X POST "localhost:9200/_reindex" -H "Content-Type: application/json" -d '{
  "source": {
    "index": "your-index"
  },
  "dest": {
    "index": "your-index-v2"
  }
}'

This operation copies only the raw data and applies the destination index's mapping. The process may take time for large indices. Monitor progress with:

bash
curl -X GET "localhost:9200/_tasks?detailed=true&actions=*reindex*"
4Verify the reindexed data

After reindexing completes, verify that documents were copied correctly and the field type is now correct:

bash
curl -X GET "localhost:9200/your-index-v2/_count?pretty"
curl -X GET "localhost:9200/your-index-v2/_mapping?pretty"

Check the document count matches the original index, and confirm the field now has the desired type in the mapping.

5Update your index alias or switch to the new index

Once verified, update your application to point to the new index. If you're using aliases, update them:

bash
curl -X POST "localhost:9200/_aliases" -H "Content-Type: application/json" -d '{
  "actions": [
    { "remove": { "index": "your-index", "alias": "your-index-alias" } },
    { "add": { "index": "your-index-v2", "alias": "your-index-alias" } }
  ]
}'

This way, your application continues using the same alias name while seamlessly pointing to the new index.

6Delete the old index (optional, after verification)

Once you've confirmed everything works with the new index and your application is using it, you can delete the old index to free up storage:

bash
curl -X DELETE "localhost:9200/your-index"

Only do this after you're completely confident the migration is successful.

Advanced notes

For large indices (over 5GB), reindexing can be slow and resource-intensive. Consider these advanced approaches:

Multi-field approach: Instead of reindexing, add a new field with the desired type alongside the existing field using multi-fields. This avoids reindexing but increases storage:

json
{
  "mappings": {
    "properties": {
      "your-field": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword"
          }
        }
      }
    }
  }
}

Then query the new sub-field as "your-field.keyword".

Reindex with script: If you need to transform data during reindexing, use a script:

json
{
  "source": { "index": "your-index" },
  "dest": { "index": "your-index-v2" },
  "script": {
    "source": "ctx._source.your-field = ctx._source.your-field.toString()"
  }
}

Index lifecycle management: Use ILM policies to automate rollover to new indices with updated mappings for time-series data.

Frequently asked questions

What does "IllegalArgumentException" mean?
This error occurs when you attempt to change the data type of an existing field in an Elasticsearch mapping. For example, trying to change a field from "text" to "keyword" type. Elasticsearch prevents this operation by design because changing field types could invalidate already-indexed data and break existing queries.
How do I fix "IllegalArgumentException"?
Elasticsearch doesn't allow changing an existing field's type once it's been mapped. You need to create a new index with the correct mapping and reindex your data to fix this error.
What causes "IllegalArgumentException"?
Attempting to change a field's type directly via PUT mapping API on an existing index Schema evolution where a field was initially mapped as one type but needs to be another type Data ingestion tools sending data with unexpected types that conflict with existing mappings
Is the "IllegalArgumentException" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading