ValidationException: One or more parameter values were invalid: Missing the key orderId in the item

What it means

DynamoDB validates a request before it does anything with it. Keys are checked against the table's schema, expressions are parsed, attribute values are type-checked, and if any of it is wrong the request is rejected without touching the table. ValidationException is that rejection.

The practical consequence is that this error is never transient. Throttling clears, conflicts resolve, capacity scales — none of that applies here. The request as constructed will be refused every time it is sent, so a retry loop around one of these does nothing except consume the function's remaining time and then fail anyway. Recognising that early saves a lot of confused debugging.

The compensating virtue is that DynamoDB's validation messages are among the most specific AWS produces. They name the missing key, the mismatched schema element, the reserved word, the invalid value. The whole diagnosis is in the sentence after the colon — which is exactly the part that gets lost when code logs error.name or catches broadly and re-raises something generic.

Two causes account for most real occurrences. The first is an absent upstream field: a path parameter, a body field, or an environment variable that is undefined, which serialises to a missing key rather than to an error at the point where it went wrong. The second is reserved words. DynamoDB reserves several hundred, and the list includes name, status, size, timestamp, data, year and value — words that are almost impossible to avoid in a real schema. Using expression attribute name placeholders by default, rather than reaching for them after being told, removes that entire category.

What it looks like in CloudWatch

This is the shape the failure arrives in: the lines of one invocation scattered among everything else the log group received at the same moment.

The panel on the right is generated by running the excerpt on the left through the same parser that powers the free web stitcher — it is what the tool actually produces for this input, not an illustration of it.

How to confirm it from the logs

Read past the exception name. ValidationException on its own says nothing; the sentence after the colon is the entire diagnosis, and it is unusually specific. "Missing the key" names the attribute. "The provided key element does not match the schema" means a type mismatch — a number where the table expects a string, most often. "Query condition missed key schema element" means the query has no partition key. "Attribute name is a reserved keyword" names the word.

This never appears intermittently for a fixed request shape. If some invocations succeed and others fail with the same code, the difference is in the data — a field absent on some records, or a value of an unexpected type.

Causes, most likely first

Fixes

js// Rejected: `status` and `name` are reserved words.
// UpdateExpression: "SET status = :s, name = :n"

await client.send(new UpdateCommand({
  TableName: "orders",
  Key: { orderId },
  UpdateExpression: "SET #status = :status, #name = :name",
  ExpressionAttributeNames: { "#status": "status", "#name": "name" },
  ExpressionAttributeValues: { ":status": "shipped", ":name": label }
}));

jsconst orderId = event.pathParameters?.orderId;
if (typeof orderId !== "string" || orderId === "") {
  return {
    statusCode: 400,
    body: JSON.stringify({ error: "orderId is required" })
  };
}

js// Table defines orderId as N. JSON gives us a string.
const key = { orderId: Number(event.pathParameters.orderId) };
if (!Number.isInteger(key.orderId)) {
  throw new Error(`orderId must be an integer, got ${event.pathParameters.orderId}`);
}

jsimport { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";

const doc = DynamoDBDocumentClient.from(client, {
  marshallOptions: {
    removeUndefinedValues: true,
    convertEmptyValues: false
  }
});

Also seen as

The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.

Related errors

Errors that show up alongside this one, or that people mistake for it.

References

• Amazon DynamoDB Developer Guide — Error handling
• Amazon DynamoDB Developer Guide — Reserved words