Elasticdump rarely fails in mysterious ways. When a run breaks, it almost always breaks at one of three points: it cannot reach the cluster, it starts fine and dies somewhere in the middle, or it finishes with a clean exit while the data on the other side is quietly wrong. Each stage has its own short list of causes: connection settings, TLS, mappings, or defaults you did not know were set the way they are.
This guide walks through the failures in the order you are likely to meet them. Work through the section that matches your symptom rather than reinstalling the tool at random — ElasticDump only needs Node.js 10 or newer, and the installation is almost never the problem. The cluster, the network and the shape of your data are where the real faults live.
It will not connect at all
Connection refused, DNS failures and timeouts
The error names differ — ECONNREFUSED, ENOTFOUND, ETIMEDOUT, EHOSTUNREACH, ECONNRESET — but they all mean the same thing at this stage: the client never got a usable answer from the cluster. ECONNREFUSED usually means the host was reached but nothing is listening on that port, or a firewall is actively rejecting the connection. ENOTFOUND and EAI_AGAIN are DNS problems: the hostname in your --input or --output URL does not resolve from the machine running ElasticDump. ETIMEDOUT and ESOCKETTIMEDOUT mean packets went out and nothing came back in time, which points at routing, a VPN that is not up, or a cluster bound to an interface you are not reaching.
Check the basics before anything clever. Confirm the URL scheme, host and port are right, and that you can reach the cluster from the same machine with a plain HTTP request. A surprising number of “ElasticDump is broken” reports end with the cluster listening on a Docker-internal address, or the tool pointed at a node that is down. If the error is hidden behind a generic failure message, add --debug to the command: it prints the actual Elasticsearch requests ElasticDump is making, which usually shows immediately whether the problem is the URL, the port, or what the cluster sent back.
One setting matters more here than people expect: --retryAttempts defaults to 0. A single transient failure — one dropped connection, one slow node — ends the run on the spot. On any real network, raise it — --retryAttempts=5, say — and let --retryDelay (5000 ms by default) space the attempts out. If individual requests are slow rather than refused, --timeout controls how long each request is allowed to take before it counts as failed.
The old “No Living connections” message
Older ElasticDump questions and forum threads are full of an error reading “No Living connections”. That wording comes from the legacy Elasticsearch JavaScript client era; it is the classic message, not one you should expect verbatim from current versions. Treat it as a label for the symptom class rather than a diagnosis: the client could not reach any node it knew about. The causes are the same ones above — wrong URL or port, the cluster down or bound elsewhere, DNS not resolving, or TLS and authentication standing in the way. Advice in old threads about checking reachability still applies even if the exact string on your screen differs.
Certificate errors against a secured Elasticsearch 8 cluster
Elasticsearch 8 clusters are HTTPS by default, often with a self-signed certificate authority. Point ElasticDump at one without telling it about that CA and the TLS handshake fails before any data moves — typically a certificate validation error from Node.js rather than anything from Elasticsearch.
There are two fixes, and they are not equal. The quick bypass is to disable certificate verification for the process:
NODE_TLS_REJECT_UNAUTHORIZED=0 elasticdump --input=https://localhost:9200/my-index --output=my-index.json
That works, and the README documents it for exactly this situation — but it turns off verification for every connection the process makes. The proper fix is to give ElasticDump the cluster’s CA certificate so it can verify the server properly:
elasticdump --input=https://localhost:9200/my-index --input-ca=/path/to/ca.crt --output=my-index.json
Use --input-ca for the source side and --output-ca for the destination side when the two clusters have different CAs; --ca covers both when they share one. Where the cluster also requires client certificates, --cert and --key (with --pass if the key is protected, or --tlsAuth) supply them. Rule of thumb: use the bypass to confirm TLS is really your problem, then switch to the CA flags for anything you will run more than once.
Authentication failures: 401 and 403 responses
A 401 means the cluster does not accept who you are; a 403 means it knows who you are but will not let you do that. Both appear when a request arrives with no credentials, wrong credentials, or a user without the privileges the operation needs — reading an index on the source side, or writing and creating indices on the destination side.
Credentials can be embedded in the URL, but the cleaner option is the environment variables ElasticDump reads for each side:
export ELASTICDUMP_INPUT_USERNAME=elastic export ELASTICDUMP_INPUT_PASSWORD='your-password' export ELASTICDUMP_OUTPUT_USERNAME=elastic export ELASTICDUMP_OUTPUT_PASSWORD='your-password'
Keeping passwords out of the command line also keeps them out of shell history and process listings. If your requests pass through a proxy that injects its own requirements, custom --headers can be added to the requests. On AWS-managed OpenSearch, IAM signing is the alternative to basic credentials: --awsAccessKeyId and --awsSecretAccessKey, a --sessionToken where needed, or --awsChain to pick credentials up from the environment in the usual AWS order.
The dump starts, then dies partway
The scroll context expires on long exports
ElasticDump reads an index through the Scroll API: Elasticsearch holds a search context — a frozen view of the results — and hands back batches until the export finishes. The --scrollTime option, 10 minutes by default, is how long that context is kept alive between requests. The context only has to survive from one batch to the next — but a stalled network, a heavily loaded node or a slow destination can leave a gap long enough for the context to be dropped, and the next scroll request comes back with an error saying the search context is gone.
Three things help. First, raise --scrollTime (for example --scrollTime=30m) when exports are large or the pipeline is slow. Second, consider the newer reading mode: --searchAfter (which needs Elasticsearch 7.17.0 or newer) pages through results using sort values, and --pit keeps a point-in-time view open with --pitKeepAlive (5 minutes by default) — avoiding the long-lived scroll context altogether. Third, a dead run does not always mean starting again: --scrollId resumes reading from the last scroll ID while that context is still alive, and --offset restarts a file output from the last known written line. Treat --offset as approximate — dumps are not sorted, so the tool cannot guarantee the skipped lines are exactly the ones already written.
The reading methods behind a big export are worth comparing before you rely on one; how to get all data from an Elasticsearch index walks through the plain search, scroll and search_after approaches side by side.
Out-of-memory failures on very large dumps
When a run dies with memory errors, the batch is usually the lever. --limit controls how many documents move per batch and defaults to 100; lowering it shrinks the amount of data held in flight at once. When the output is a file, --fileSize splits the dump into chunks instead of one growing file, which helps with the overflow and out-of-memory exceptions that appear on very large dumps. If you are dumping many indices, doing them one at a time keeps the total memory footprint predictable instead of letting many large exports compete.
“The output file already exists”
This one stops a run before it starts, and the message is literal: the file transport will not overwrite an existing file. ElasticDump throws an exception rather than quietly replacing last week’s dump — a deliberate safety behaviour that still catches people out in scripts and cron jobs where the old file is sitting there from the previous run. Either delete the old file, or add --overwrite when replacing it really is what you intend.
The dump looks shuffled — that is not an error
Since version 6.1.0, ElasticDump processes records with overlapping promises, so the order documents are written is not guaranteed to be sequential. A dump file whose documents look out of order compared with the source index is expected behaviour, not corruption — the documents are all there, just not written in a strict queue. Do not waste an afternoon “fixing” this one; check counts instead, which is the verification that actually matters (see below).
The load finishes — but data is missing or rejected
This is the most dangerous category, because nothing looks broken. The command exits, the log scrolls to the end, and only a document count reveals that the destination is short.
Silent write failures: the default nobody expects
--ignore-es-write-errors defaults to true. It explains a large share of “ElasticDump lost my data” reports: when Elasticsearch rejects documents during a load, ElasticDump notes the errors and keeps going rather than aborting the run. That default exists so one bad document does not kill a million-document load — but it also means a “successful” run can have dropped writes anywhere along the way.
The fix is a workflow habit, not just a flag. After every load, compare document counts between source and destination — the _count API on both indices takes seconds. If the numbers disagree, re-run with write errors visible and read the rejections; they almost always lead to the next problem.
mapper_parsing_exception: the mapping arrived after the data
When Elasticsearch refuses documents with a mapper_parsing_exception, the values in the documents do not match the index mapping — a field mapped as a date receives a string that is not a date, or a field mapped as an object receives a plain value. There is a specifically ElasticDump-flavoured way to cause this, and it is the most common load failure of all: load the data before the mapping exists.
ElasticDump’s own notes confirm indices are auto-created on import: if your first pass writes documents where the index does not exist yet, Elasticsearch creates it on the spot and dynamically guesses field types from those first documents. The guesses only have to be wrong once — a numeric-looking string becomes a long, a date becomes text — and from then on, any document whose real value does not fit the guessed type is rejected. This is the practical side of a general truth about the engine: Elasticsearch is a database with a schema whether you planned one or not, and its mappings are enforced on every write.
The recovery is mechanical:
- Delete the auto-created index on the destination.
- Copy the structure first, in order:
--type=analyzer, then--type=mapping. - Only then run the
--type=datapass.
That ordering is not a superstition; it is the sequence the project’s own examples use for cluster-to-cluster copies, and following it prevents the whole class of error. If the mapping itself is the problem — genuinely wrong types in the source — fix the mapping on the destination before loading, because no copy order will rescue documents that clash with a correct-but-different schema.
Old mappings and templates rejected by modern clusters
Crossing the Elasticsearch 6-to-7 boundary with an old dump brings a different rejection: “Root mapping definition has unsupported parameters”. Pre-7.0 mappings and templates often carry a type name, an _all field, or settings like index: not_analyzed, all of which 7.x and later simply refuse. The README’s notes give the related housekeeping rules: Elasticsearch 6 removed the template property for index templates in favour of index_patterns, and Elasticsearch 7 removed the type property from templates entirely. A dump file captured from an old cluster can contain all of these. The fix is unglamorous: open the mapping or template file, strip the unsupported constructs, and load the cleaned version — there is no flag that modernises them for you.
Version mismatch can also bite at the tool level. ElasticDump’s default queries target Elasticsearch 5 and later, and against OpenSearch it detects the cluster flavour automatically, with --force-os-version (default 7.10.2) available when detection needs a nudge. If a run behaves strangely against a very old cluster or an OpenSearch variant, that detection is worth checking early.
A working order for diagnosing any failure
| Symptom | First thing to check |
|---|---|
| Connection refused / DNS error | URL, port, reachability from the same machine; --debug output |
| Certificate validation error | --input-ca / --output-ca with the cluster CA |
| 401 / 403 | Credentials in the URL or the ELASTICDUMP_* environment variables; user privileges |
| Run dies on a transient network error | --retryAttempts (default 0) and --retryDelay |
| Error partway through a huge export | Scroll context: raise --scrollTime, or switch to --searchAfter / --pit |
| Out of memory | Lower --limit; split file output with --fileSize |
| Refuses to write the output file | Existing file — remove it or add --overwrite |
| Load exits 0 but counts are short | Write errors were ignored by default — compare _count on both sides |
mapper_parsing_exception |
Mapping loaded after data — delete index, load analyzer → mapping → data |
| Unsupported mapping parameters | Pre-7 constructs in an old dump — clean the mapping/template file |
FAQ
Why does ElasticDump connect with curl but fail with a certificate error?
Because curl and Node.js use different certificate stores and defaults. If the cluster uses a self-signed CA, ElasticDump needs to be told about it explicitly with --input-ca or --output-ca. The NODE_TLS_REJECT_UNAUTHORIZED=0 bypass confirms the diagnosis, but passing the CA is the fix worth keeping.
The command exited successfully. How do I know the copy is complete?
You do not — not from the exit code alone. Because --ignore-es-write-errors defaults to true, failed writes do not fail the run. Compare the document count of the source and destination indices after every load; a mismatch means some documents were rejected, and the load output will say why.
My export keeps dying at roughly the same point. What is it?
On a long export, the usual suspect is the scroll context expiring between batches — the default --scrollTime is 10 minutes. Raise it, or move to --searchAfter with --pit on Elasticsearch 7.17+, and resume an interrupted run with --scrollId or --offset instead of starting over.
Is the answer to reinstall or upgrade Node?
Almost never. ElasticDump requires Node.js 10 or later, and beyond that the failures in this guide — connection, TLS, auth, scroll, mappings — live in configuration and data, not the installation.
Do I even need ElasticDump for this job, or should I use a snapshot?
If the job is a backup or a same-version restore, a snapshot is the supported route and ElasticDump is the wrong tool; if you need a file, a subset, a transform, or a move across versions, ElasticDump is the right one. The comparison in Elasticdump vs snapshot and restore works through that decision in full.
Conclusion
Elasticdump fails in patterned ways, and that is good news: connection errors are reachability, TLS or credentials; mid-dump deaths are scroll contexts, memory or retries that were never configured; and quiet data loss is almost always the write-errors default hiding rejections, very often caused by data arriving before its mapping. Diagnose by stage, fix the actual cause, and verify counts at the end — a dump you have counted is a dump you can trust, and a run that merely exited cleanly has not yet earned that trust.