Debugging ElasticPress

ElasticPress is a sophisticated plugin that tightly integrates with WordPress core, themes, and plugins. As a result, debugging ElasticPress can be tricky business for even experienced developers. Having been exposed to many debugging questions in our GitHub repository, we thought we’d take a deeper dive into a couple of the most common issues.

The first thing to do whenever encountering an issue with ElasticPress is to install the Debug Bar and Debug Bar ElasticPress plugin. The Debug Bar ElasticPress plugin adds a pane to the Debug Bar that shows every query sent to Elasticsearch and the response to each query.

Scenario 1: Missing Index

Here are the Debug Bar pane results for a problematic search query:

The first query sent is successful (200 response). This query determines if Elasticsearch is running as well as what Elasticsearch plugins are available. The second query returns a 404. Since we know Elasticsearch is running, the issue is that the index I am querying against does not exist. To fix this problem, I’d run a re-index.

Scenario 2: Missing Mapping

Here are the Debug Bar pane results for another problematic search query:

Again, our first query is successful so we know Elasticsearch is running. Our second query returns an HTTP 400 with a strange error: “field [post_date_gmt] is of type [indexed,tokenized], but only numeric types are supported”. This denotes an issue with the post_date_gmt field. This is often the result of a put mapping issue. We check the mapping by sending a GET request in our browser (or something like Postman) to our Elasticsearch cluster’s _mapping endpoint (for me this would be http://elasticsearch:9200/localhost-1/post/_mapping). The truncated Postman response looks like this:

"post_content": {
    "type": "text",
    "fields": {
        "keyword": {
            "type": "keyword",
            "ignore_above": 256
        }
    }
},
"post_date": {
    "type": "text",
    "fields": {
        "keyword": {
            "type": "keyword",
            "ignore_above": 256
        }
    }
},
"post_date_gmt": {
    "type": "text",
    "fields": {
        "keyword": {
            "type": "keyword",
            "ignore_above": 256
        }
    }
}

The response shows post_date_gmt is of type “text”. However, ElasticPress’s mapping clearly defines post_date_gmt as type “date”. This tells us our put mapping failed.

In Elasticsearch, a put mapping is optional. If we index data without a mapping, Elasticsearch will infer data types, resulting in a “text” type. Elasticsearch is throwing an error since we are ordering by date on a text field. Put mapping can fail for a number of reasons. In order to trace down the problem, I would run the WP-CLI command “wp elasticpress put-mapping”. I’d then debug the result of that request to trace down the point of failure.

Keep an eye on this blog for future debugging and troubleshooting tips.