Error Log: You’ll see this error when you try to use the _update API on a document that doesn’t exist.
JSON
None
{
"error": {
"root_cause": [
{
"type": "document_missing_exception",
"reason": "[_doc][doc-id-123]: document missing",
"index_uuid": "...",
"shard": "0",
"index": "my-index"
}
],
"type": "document_missing_exception",
"reason": "[_doc][doc-id-123]: document missing",
"index_uuid": "...",
"shard": "0",
"index": "my-index"
},
"status": 404
}Why… is this happening? This error is very specific. You sent an _update request for a document (e.g., POST /my-index/_update/doc-id-123), but that document ID does not exist in the index.
The _update API is designed to modify an existing document. It is not designed to create a new one. If it can’t find the document, it fails with this 404 (Not Found) error.
This is different from an INDEX command (e.g., PUT /my-index/_doc/doc-id-123), which will happily create or overwrite a document. You are getting this error because you specifically chose the _update operation, and the document wasn’t there to be updated.
Best Practice:
1. Use “Upsert” (the best fix): The _update API has a built-in feature called upsert (a mix of “update” and “insert”). It tells OpenSearch: “Try to update this document. If you can’t find it, use this other document to create it instead.”
JSON
None
POST /my-index/_update/doc-id-123
{
"doc": { "counter": 1 }, // This is applied if the doc EXISTS
"upsert": {
"counter": 1, // This is used if the doc does NOT exist
"created_at": "2025-11-03T20:00:00Z"
}
}2. This single command gracefully handles both cases and will not throw a DocumentMissingException.
3. Check your logic: If you never expect to create a new document with this call, then this error is a valid bug in your application. It means your application’s logic is flawed and is trying to update a document ID that it shouldn’t be.
What else can I do? “Upsert” logic is a fundamental part of data ingestion. If you’re struggling to build a resilient data pipeline, the OpenSearch community can share best practices. For direct support, you can also contact us in The OpenSearch Slack Channel in #General.
