DynamoDB update expressions: SET, REMOVE, ADD and DELETE

A DynamoDB UpdateExpression changes attributes on one item identified by its complete primary key. Use SET to assign values, REMOVE to delete attributes, ADD to increment numbers or merge sets, and DELETE to subtract set members. You can combine all four clauses in one atomic UpdateItem request, with each clause keyword appearing at most once. If the item does not exist, the update can create it; add a ConditionExpression when creation or an unexpected overwrite must be rejected.

The examples below ran against DynamoDB Local on port 8000. Their outputs show actual item contents, including failed updates that left the item unchanged. Local tests verify expression behavior; billing and service limits are checked against AWS documentation.

DynamoDB update expression syntax

Separate actions inside a clause with commas. Separate different clauses with spaces. Clause order in the string is flexible. SET a = :a SET b = :b is invalid; use one SET containing both assignments. DELETE here removes set members; deleting an entire item uses the separate DeleteItem API.

A name beginning with # belongs in ExpressionAttributeNames. A value beginning with : belongs in ExpressionAttributeValues. They are separate maps, and their entries must match the tokens actually used in the update or condition. Alias reserved words such as status, and names containing punctuation. Alias each segment of a nested path separately: #profile.#city. Mapping one alias to profile.city addresses a literal attribute with a dot in its name.

The AWS update-expression reference defines the grammar. Unlike PutItem, an update preserves attributes it does not target. Replacing a whole map with SET, however, replaces that map's contents, including members omitted from the new value.

Run the examples locally

Use Node.js 20 or later, a disposable directory and a fresh local container. These commands install dependencies there, with no AWS account required:

# Run in a new directory, with Docker, Node.js and AWS CLI v2 installed.
docker run -d --rm --name dynamodb-local -p 8000:8000 \
  amazon/dynamodb-local:latest -jar DynamoDBLocal.jar \
  -inMemory -sharedDb -disableTelemetry
npm init -y
npm pkg set type=module
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @aws-sdk/util-dynamodb
npm install --save-dev tsx typescript @types/node
python3 -m venv venv
venv/bin/pip install boto3
# Run in a new directory, with Docker, Node.js and AWS CLI v2 installed.
docker run -d --rm --name dynamodb-local -p 8000:8000 \
  amazon/dynamodb-local:latest -jar DynamoDBLocal.jar \
  -inMemory -sharedDb -disableTelemetry
npm init -y
npm pkg set type=module
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @aws-sdk/util-dynamodb
npm install --save-dev tsx typescript @types/node
python3 -m venv venv
venv/bin/pip install boto3

Save this shared fixture as setup.mjs. It creates UpdateExpressionDemo, whose only key is the String attribute pk. On a table with a sort key, supply both key attributes in every request.

import {
  CreateTableCommand, DynamoDBClient, waitUntilTableExists,
} from "@aws-sdk/client-dynamodb"
import {
  DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, UpdateCommand,
} from "@aws-sdk/lib-dynamodb"
import { unmarshall } from "@aws-sdk/util-dynamodb"

export const low = new DynamoDBClient({
  endpoint: "http://localhost:8000",
  region: "us-east-1",
  credentials: { accessKeyId: "fake", secretAccessKey: "fake" },
})
export const doc = DynamoDBDocumentClient.from(low)
export const TableName = "UpdateExpressionDemo"
export const Key = { pk: "item-1" }
try {
  await low.send(new CreateTableCommand({
    TableName,
    KeySchema: [{ AttributeName: "pk", KeyType: "HASH" }],
    AttributeDefinitions: [{ AttributeName: "pk", AttributeType: "S" }],
    BillingMode: "PAY_PER_REQUEST",
  }))
} catch (error) {
  if (error.name !== "ResourceInUseException") throw error
}
await waitUntilTableExists({ client: low, maxWaitTime: 30 }, { TableName })

export const read = async () => (await doc.send(new GetCommand({
  TableName, Key, ConsistentRead: true,
}))).Item ?? null

export function normalize(value) {
  if (value instanceof Set) return { $set: [...value].sort() }
  if (Array.isArray(value)) return value.map(normalize)
  if (value && typeof value === "object") {
    return Object.fromEntries(Object.keys(value).sort()
      .map(key => [key, normalize(value[key])]))
  }
  return value
}
export const print = value => console.log(JSON.stringify(normalize(value)))

// Each example replaces only item-1 in this disposable local table.
export async function example(seed, request, options = {}) {
  if (seed === null) await doc.send(new DeleteCommand({ TableName, Key }))
  else await doc.send(new PutCommand({ TableName, Item: { ...seed, ...Key } }))
  const before = await read()
  let result
  try {
    result = await doc.send(new UpdateCommand({
      ReturnValues: "ALL_NEW", ...request, TableName, Key,
    }))
  } catch (error) {
    if (!options.expectError) throw error
    print({ before, error: `${error.name}: ${error.message}`, after: await read(),
      ...(error.Item ? { failureItem: unmarshall(error.Item) } : {}) })
    return
  }
  if (options.expectError) throw new Error("Expected the update to fail")
  const after = await read()
  print({ before, after, ...(options.showReturn
    ? { mode: request.ReturnValues, returned: result.Attributes ?? null } : {}) })
  return after
}
import {
  CreateTableCommand, DynamoDBClient, waitUntilTableExists,
} from "@aws-sdk/client-dynamodb"
import {
  DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, UpdateCommand,
} from "@aws-sdk/lib-dynamodb"
import { unmarshall } from "@aws-sdk/util-dynamodb"

export const low = new DynamoDBClient({
  endpoint: "http://localhost:8000",
  region: "us-east-1",
  credentials: { accessKeyId: "fake", secretAccessKey: "fake" },
})
export const doc = DynamoDBDocumentClient.from(low)
export const TableName = "UpdateExpressionDemo"
export const Key = { pk: "item-1" }
try {
  await low.send(new CreateTableCommand({
    TableName,
    KeySchema: [{ AttributeName: "pk", KeyType: "HASH" }],
    AttributeDefinitions: [{ AttributeName: "pk", AttributeType: "S" }],
    BillingMode: "PAY_PER_REQUEST",
  }))
} catch (error) {
  if (error.name !== "ResourceInUseException") throw error
}
await waitUntilTableExists({ client: low, maxWaitTime: 30 }, { TableName })

export const read = async () => (await doc.send(new GetCommand({
  TableName, Key, ConsistentRead: true,
}))).Item ?? null

export function normalize(value) {
  if (value instanceof Set) return { $set: [...value].sort() }
  if (Array.isArray(value)) return value.map(normalize)
  if (value && typeof value === "object") {
    return Object.fromEntries(Object.keys(value).sort()
      .map(key => [key, normalize(value[key])]))
  }
  return value
}
export const print = value => console.log(JSON.stringify(normalize(value)))

// Each example replaces only item-1 in this disposable local table.
export async function example(seed, request, options = {}) {
  if (seed === null) await doc.send(new DeleteCommand({ TableName, Key }))
  else await doc.send(new PutCommand({ TableName, Item: { ...seed, ...Key } }))
  const before = await read()
  let result
  try {
    result = await doc.send(new UpdateCommand({
      ReturnValues: "ALL_NEW", ...request, TableName, Key,
    }))
  } catch (error) {
    if (!options.expectError) throw error
    print({ before, error: `${error.name}: ${error.message}`, after: await read(),
      ...(error.Item ? { failureItem: unmarshall(error.Item) } : {}) })
    return
  }
  if (options.expectError) throw new Error("Expected the update to fail")
  const after = await read()
  print({ before, after, ...(options.showReturn
    ? { mode: request.ReturnValues, returned: result.Attributes ?? null } : {}) })
  return after
}

Every JavaScript example imports that file. Save each block under its stated filename and run node filename.mjs. The fixture replaces item-1 before each case, then reads it before and after the update. Those reads are test instrumentation; an application can normally use the update's ReturnValues without extra reads.

Output keys are sorted for reproducibility. A displayed {"$set":[...]} represents an SDK Set, with sorted members for display only; DynamoDB sets have no order. before: null means the item was absent. This display convention is not a DynamoDB storage format.

Combine SET, REMOVE, ADD and DELETE in one update

Save as clauses.mjs. This publishes an item, removes a temporary flag, adds stock and removes an old tag in one request:

import { example } from "./setup.mjs"

await example({
  status: "draft", obsolete: true, stock: 5,
  tags: new Set(["sale", "old"]),
}, {
  UpdateExpression: "SET #s = :s REMOVE #o ADD #n :n DELETE #t :t",
  ExpressionAttributeNames: {
    "#s": "status", "#o": "obsolete", "#n": "stock", "#t": "tags",
  },
  ExpressionAttributeValues: { ":s": "live", ":n": 2, ":t": new Set(["old"]) },
})
import { example } from "./setup.mjs"

await example({
  status: "draft", obsolete: true, stock: 5,
  tags: new Set(["sale", "old"]),
}, {
  UpdateExpression: "SET #s = :s REMOVE #o ADD #n :n DELETE #t :t",
  ExpressionAttributeNames: {
    "#s": "status", "#o": "obsolete", "#n": "stock", "#t": "tags",
  },
  ExpressionAttributeValues: { ":s": "live", ":n": 2, ":t": new Set(["old"]) },
})

{"after":{"pk":"item-1","status":"live","stock":7,"tags":{"$set":["sale"]}},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5,"tags":{"$set":["old","sale"]}}}
{"after":{"pk":"item-1","status":"live","stock":7,"tags":{"$set":["sale"]}},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5,"tags":{"$set":["old","sale"]}}}

The four changes succeed together. A malformed action or a failed condition prevents the whole update.

SET: assignments, arithmetic and if_not_exists

SET overwrites an existing value or creates an attribute. Arithmetic supports addition and subtraction on Numbers. if_not_exists(path, fallback) supplies a default when that attribute is absent; an existing NULL attribute still exists and does not select the fallback.

Save as set.mjs. Both cases subtract stock, but only the first writes created:

import { example } from "./setup.mjs"

for (const seed of [{ stock: 5 }, { stock: 5, created: "original" }]) {
  await example(seed, {
    UpdateExpression: "SET #n = #n - :n, #c = if_not_exists(#c, :c)",
    ExpressionAttributeNames: { "#n": "stock", "#c": "created" },
    ExpressionAttributeValues: { ":n": 2, ":c": "2026-10-23" },
  })
}
import { example } from "./setup.mjs"

for (const seed of [{ stock: 5 }, { stock: 5, created: "original" }]) {
  await example(seed, {
    UpdateExpression: "SET #n = #n - :n, #c = if_not_exists(#c, :c)",
    ExpressionAttributeNames: { "#n": "stock", "#c": "created" },
    ExpressionAttributeValues: { ":n": 2, ":c": "2026-10-23" },
  })
}

{"after":{"created":"2026-10-23","pk":"item-1","stock":3},"before":{"pk":"item-1","stock":5}}
{"after":{"created":"original","pk":"item-1","stock":3},"before":{"created":"original","pk":"item-1","stock":5}}
{"after":{"created":"2026-10-23","pk":"item-1","stock":3},"before":{"pk":"item-1","stock":5}}
{"after":{"created":"original","pk":"item-1","stock":3},"before":{"created":"original","pk":"item-1","stock":5}}

if_not_exists is a function inside SET, not a substitute for an update condition. Other actions in the expression still run when the attribute exists. Function names are case-sensitive.

Append or prepend a DynamoDB list

list_append(left, right) concatenates two Lists. Put the existing list on the left to append, or on the right to prepend. An Array in the JavaScript document client is a List; new Set(...) is a different DynamoDB data type.

Save as lists.mjs. The first loop handles both an absent list and an existing list. The last case replaces index zero and writes beyond the list's end:

import { example } from "./setup.mjs"

for (const seed of [{}, { items: ["pen"] }]) {
  await example(seed, {
    UpdateExpression: "SET #l = list_append(if_not_exists(#l, :empty), :new)",
    ExpressionAttributeNames: { "#l": "items" },
    ExpressionAttributeValues: { ":empty": [], ":new": ["book"] },
  })
}
await example({ items: ["pen"] }, {
  UpdateExpression: "SET #l = list_append(:new, #l)",
  ExpressionAttributeNames: { "#l": "items" },
  ExpressionAttributeValues: { ":new": ["book"] },
})
await example({ items: ["pen", "book"] }, {
  UpdateExpression: "SET #l[0] = :replacement, #l[8] = :extra",
  ExpressionAttributeNames: { "#l": "items" },
  ExpressionAttributeValues: { ":replacement": "pencil", ":extra": "bag" },
})
import { example } from "./setup.mjs"

for (const seed of [{}, { items: ["pen"] }]) {
  await example(seed, {
    UpdateExpression: "SET #l = list_append(if_not_exists(#l, :empty), :new)",
    ExpressionAttributeNames: { "#l": "items" },
    ExpressionAttributeValues: { ":empty": [], ":new": ["book"] },
  })
}
await example({ items: ["pen"] }, {
  UpdateExpression: "SET #l = list_append(:new, #l)",
  ExpressionAttributeNames: { "#l": "items" },
  ExpressionAttributeValues: { ":new": ["book"] },
})
await example({ items: ["pen", "book"] }, {
  UpdateExpression: "SET #l[0] = :replacement, #l[8] = :extra",
  ExpressionAttributeNames: { "#l": "items" },
  ExpressionAttributeValues: { ":replacement": "pencil", ":extra": "bag" },
})

{"after":{"items":["book"],"pk":"item-1"},"before":{"pk":"item-1"}}
{"after":{"items":["pen","book"],"pk":"item-1"},"before":{"items":["pen"],"pk":"item-1"}}
{"after":{"items":["book","pen"],"pk":"item-1"},"before":{"items":["pen"],"pk":"item-1"}}
{"after":{"items":["pencil","book","bag"],"pk":"item-1"},"before":{"items":["pen","book"],"pk":"item-1"}}
{"after":{"items":["book"],"pk":"item-1"},"before":{"pk":"item-1"}}
{"after":{"items":["pen","book"],"pk":"item-1"},"before":{"items":["pen"],"pk":"item-1"}}
{"after":{"items":["book","pen"],"pk":"item-1"},"before":{"items":["pen"],"pk":"item-1"}}
{"after":{"items":["pencil","book","bag"],"pk":"item-1"},"before":{"items":["pen","book"],"pk":"item-1"}}

Indexes start at zero. Writing a nonexistent index appends the element; it does not create empty slots up to that index. Use list_append when appending is the intent. Concurrent position-based edits can target a different logical element after another writer changes the list; protect such edits with a version condition when identity matters.

Update a nested map attribute

Save as nested.mjs:

import { example } from "./setup.mjs"

await example({ profile: { city: "Paris", tier: "free" } }, {
  UpdateExpression: "SET #p.#c = :c",
  ExpressionAttributeNames: { "#p": "profile", "#c": "city" },
  ExpressionAttributeValues: { ":c": "Rome" },
})
import { example } from "./setup.mjs"

await example({ profile: { city: "Paris", tier: "free" } }, {
  UpdateExpression: "SET #p.#c = :c",
  ExpressionAttributeNames: { "#p": "profile", "#c": "city" },
  ExpressionAttributeValues: { ":c": "Rome" },
})

{"after":{"pk":"item-1","profile":{"city":"Rome","tier":"free"}},"before":{"pk":"item-1","profile":{"city":"Paris","tier":"free"}}}
{"after":{"pk":"item-1","profile":{"city":"Rome","tier":"free"}},"before":{"pk":"item-1","profile":{"city":"Paris","tier":"free"}}}

The sibling tier survives. The parent profile must already be a Map; DynamoDB does not construct intermediate maps for profile.city. if_not_exists(profile.city, :city) cannot repair a missing parent. The troubleshooting section shows the error and a separate initialization step.

REMOVE: delete attributes and list elements

REMOVE takes paths without values. Removing a missing top-level attribute is a no-op. Save as remove.mjs:

import { example } from "./setup.mjs"

await example({
  obsolete: true, profile: { city: "Paris", tier: "free" },
  items: ["pen", "book", "bag", "ruler"],
}, {
  UpdateExpression: "REMOVE #o, #p.#c, #l[1], #l[2], #missing",
  ExpressionAttributeNames: {
    "#o": "obsolete", "#p": "profile", "#c": "city",
    "#l": "items", "#missing": "notPresent",
  },
})
import { example } from "./setup.mjs"

await example({
  obsolete: true, profile: { city: "Paris", tier: "free" },
  items: ["pen", "book", "bag", "ruler"],
}, {
  UpdateExpression: "REMOVE #o, #p.#c, #l[1], #l[2], #missing",
  ExpressionAttributeNames: {
    "#o": "obsolete", "#p": "profile", "#c": "city",
    "#l": "items", "#missing": "notPresent",
  },
})

{"after":{"items":["pen","ruler"],"pk":"item-1","profile":{"tier":"free"}},"before":{"items":["pen","book","bag","ruler"],"obsolete":true,"pk":"item-1","profile":{"city":"Paris","tier":"free"}}}
{"after":{"items":["pen","ruler"],"pk":"item-1","profile":{"tier":"free"}},"before":{"items":["pen","book","bag","ruler"],"obsolete":true,"pk":"item-1","profile":{"city":"Paris","tier":"free"}}}

Both list indexes refer to the original list: book and bag disappear, then the remaining elements shift together. No need to reverse the indexes within one expression. Across separate requests, indexes can shift between calls. Removing a nested member also requires a valid parent path.

ADD: increment a counter or add to a set

A Number operand increments the existing Number. A negative operand decrements it. If the attribute is absent, DynamoDB starts from zero. A Set operand unions its members with the stored set, without duplicates; an absent set is created. Both sets must have the same member type: String, Number or Binary.

Save as add.mjs. The final case uses SET arithmetic for a nested counter because ADD only accepts top-level paths:

import { example } from "./setup.mjs"

for (const seed of [{}, { stock: 5, tags: new Set(["sale"]) }]) {
  await example(seed, {
    UpdateExpression: "ADD #n :n, #t :t",
    ExpressionAttributeNames: { "#n": "stock", "#t": "tags" },
    ExpressionAttributeValues: { ":n": 2, ":t": new Set(["sale", "new"]) },
  })
}
await example({ profile: {} }, {
  UpdateExpression: "SET #p.#n = if_not_exists(#p.#n, :zero) + :n",
  ExpressionAttributeNames: { "#p": "profile", "#n": "visits" },
  ExpressionAttributeValues: { ":zero": 0, ":n": 1 },
})
import { example } from "./setup.mjs"

for (const seed of [{}, { stock: 5, tags: new Set(["sale"]) }]) {
  await example(seed, {
    UpdateExpression: "ADD #n :n, #t :t",
    ExpressionAttributeNames: { "#n": "stock", "#t": "tags" },
    ExpressionAttributeValues: { ":n": 2, ":t": new Set(["sale", "new"]) },
  })
}
await example({ profile: {} }, {
  UpdateExpression: "SET #p.#n = if_not_exists(#p.#n, :zero) + :n",
  ExpressionAttributeNames: { "#p": "profile", "#n": "visits" },
  ExpressionAttributeValues: { ":zero": 0, ":n": 1 },
})

{"after":{"pk":"item-1","stock":2,"tags":{"$set":["new","sale"]}},"before":{"pk":"item-1"}}
{"after":{"pk":"item-1","stock":7,"tags":{"$set":["new","sale"]}},"before":{"pk":"item-1","stock":5,"tags":{"$set":["sale"]}}}
{"after":{"pk":"item-1","profile":{"visits":1}},"before":{"pk":"item-1","profile":{}}}
{"after":{"pk":"item-1","stock":2,"tags":{"$set":["new","sale"]}},"before":{"pk":"item-1"}}
{"after":{"pk":"item-1","stock":7,"tags":{"$set":["new","sale"]}},"before":{"pk":"item-1","stock":5,"tags":{"$set":["sale"]}}}
{"after":{"pk":"item-1","profile":{"visits":1}},"before":{"pk":"item-1","profile":{}}}

The counter operation is atomic, so it avoids a read-then-write lost increment. It is not idempotent: retrying a successful increment increments again. The same applies to SET #n = #n + :n and to list appends. A clause named SET does not itself make an operation safe to replay. Use a conditional version or an application idempotency design when a timeout leaves success uncertain. See atomic counter troubleshooting for missing attributes and type mismatches.

DELETE: remove members from a set

Save as delete.mjs:

import { example } from "./setup.mjs"

for (const tags of [new Set(["old", "sale"]), new Set(["old"])]) {
  await example({ tags }, {
    UpdateExpression: "DELETE #t :t",
    ExpressionAttributeNames: { "#t": "tags" },
    ExpressionAttributeValues: { ":t": new Set(["old"]) },
  })
}
import { example } from "./setup.mjs"

for (const tags of [new Set(["old", "sale"]), new Set(["old"])]) {
  await example({ tags }, {
    UpdateExpression: "DELETE #t :t",
    ExpressionAttributeNames: { "#t": "tags" },
    ExpressionAttributeValues: { ":t": new Set(["old"]) },
  })
}

{"after":{"pk":"item-1","tags":{"$set":["sale"]}},"before":{"pk":"item-1","tags":{"$set":["old","sale"]}}}
{"after":{"pk":"item-1"},"before":{"pk":"item-1","tags":{"$set":["old"]}}}
{"after":{"pk":"item-1","tags":{"$set":["sale"]}},"before":{"pk":"item-1","tags":{"$set":["old","sale"]}}}
{"after":{"pk":"item-1"},"before":{"pk":"item-1","tags":{"$set":["old"]}}}

The first case keeps sale; the second removes the tags attribute because no members remain. You cannot pass an empty set as the operand. Use REMOVE #tags to remove the whole attribute, and a List plus SET/REMOVE when order or duplicate entries matter.

How are multiple actions evaluated?

Right-hand attribute references use the item's values before the update, even if another action changes or removes the referenced attribute. The expression is not a sequence of JavaScript assignments.

Save as evaluation.mjs:

import { example } from "./setup.mjs"

await example({ stock: 5 }, {
  UpdateExpression: "SET #n = #n + :n, #previous = #n",
  ExpressionAttributeNames: { "#n": "stock", "#previous": "previousStock" },
  ExpressionAttributeValues: { ":n": 2 },
})
import { example } from "./setup.mjs"

await example({ stock: 5 }, {
  UpdateExpression: "SET #n = #n + :n, #previous = #n",
  ExpressionAttributeNames: { "#n": "stock", "#previous": "previousStock" },
  ExpressionAttributeValues: { ":n": 2 },
})

{"after":{"pk":"item-1","previousStock":5,"stock":7},"before":{"pk":"item-1","stock":5}}
{"after":{"pk":"item-1","previousStock":5,"stock":7},"before":{"pk":"item-1","stock":5}}

previousStock becomes 5, not 7. Referencing a path is allowed; assigning overlapping target paths is not. For example, trying to set both profile and profile.city in one expression is rejected. Reordering clauses cannot resolve that overlap.

UpdateItem upserts unless a condition prevents it

Save as upsert.mjs. Both cases start with no item. The second adds an existence condition:

import { example } from "./setup.mjs"

const request = {
  UpdateExpression: "SET #s = :s",
  ExpressionAttributeNames: { "#s": "status" },
  ExpressionAttributeValues: { ":s": "live" },
}
await example(null, request)
await example(null, {
  ...request,
  ConditionExpression: "attribute_exists(#pk)",
  ExpressionAttributeNames: { ...request.ExpressionAttributeNames, "#pk": "pk" },
}, { expectError: true })
import { example } from "./setup.mjs"

const request = {
  UpdateExpression: "SET #s = :s",
  ExpressionAttributeNames: { "#s": "status" },
  ExpressionAttributeValues: { ":s": "live" },
}
await example(null, request)
await example(null, {
  ...request,
  ConditionExpression: "attribute_exists(#pk)",
  ExpressionAttributeNames: { ...request.ExpressionAttributeNames, "#pk": "pk" },
}, { expectError: true })

{"after":{"pk":"item-1","status":"live"},"before":null}
{"after":null,"before":null,"error":"ConditionalCheckFailedException: The conditional request failed"}
{"after":{"pk":"item-1","status":"live"},"before":null}
{"after":null,"before":null,"error":"ConditionalCheckFailedException: The conditional request failed"}

The first creates the key and the assigned attributes. The second fails without creating anything. An upsert still needs a valid expression: arithmetic on an absent Number without a default, or an update through a missing map, can fail.

Conditional updates and optimistic locking

A condition is tested atomically with the write. The conditional update guide covers existence and value checks. For optimistic locking, compare the version you read and increment it in the same update.

Save as conditional.mjs. These independent cases start at version 3; one caller expects that version and the other expects an older version:

import { example } from "./setup.mjs"

for (const expected of [3, 2]) {
  await example({ stock: 5, version: 3 }, {
    UpdateExpression: "SET #n = #n - :qty, #v = #v + :one",
    ConditionExpression: "attribute_exists(#pk) AND #v = :expected AND #n >= :qty",
    ExpressionAttributeNames: { "#pk": "pk", "#n": "stock", "#v": "version" },
    ExpressionAttributeValues: { ":qty": 2, ":one": 1, ":expected": expected },
    ReturnValuesOnConditionCheckFailure: "ALL_OLD",
  }, { expectError: expected === 2 })
}
import { example } from "./setup.mjs"

for (const expected of [3, 2]) {
  await example({ stock: 5, version: 3 }, {
    UpdateExpression: "SET #n = #n - :qty, #v = #v + :one",
    ConditionExpression: "attribute_exists(#pk) AND #v = :expected AND #n >= :qty",
    ExpressionAttributeNames: { "#pk": "pk", "#n": "stock", "#v": "version" },
    ExpressionAttributeValues: { ":qty": 2, ":one": 1, ":expected": expected },
    ReturnValuesOnConditionCheckFailure: "ALL_OLD",
  }, { expectError: expected === 2 })
}

{"after":{"pk":"item-1","stock":3,"version":4},"before":{"pk":"item-1","stock":5,"version":3}}
{"after":{"pk":"item-1","stock":5,"version":3},"before":{"pk":"item-1","stock":5,"version":3},"error":"ConditionalCheckFailedException: The conditional request failed","failureItem":{"pk":"item-1","stock":5,"version":3}}
{"after":{"pk":"item-1","stock":3,"version":4},"before":{"pk":"item-1","stock":5,"version":3}}
{"after":{"pk":"item-1","stock":5,"version":3},"before":{"pk":"item-1","stock":5,"version":3},"error":"ConditionalCheckFailedException: The conditional request failed","failureItem":{"pk":"item-1","stock":5,"version":3}}

The failed request leaves stock and version unchanged. ReturnValuesOnConditionCheckFailure: "ALL_OLD" returns the item that failed the condition in the exception's Item field. In the tested JavaScript SDK, that exception field is low-level DynamoDB JSON, so the fixture calls unmarshall(error.Item). It can be absent when the item does not exist. Handle the conflict in application logic rather than blindly repeating the same condition.

Keeping historical versions is a separate requirement from rejecting stale writes; see DynamoDB data versioning for that model.

ReturnValues: what does UpdateItem return?

ReturnValues controls a successful response's Attributes field. Returned attributes are strongly consistent and do not consume read capacity. ReturnValuesOnConditionCheckFailure is separate and accepts only ALL_OLD or NONE. These behaviors are specified in the UpdateItem API reference.

Save as returns.mjs. Every iteration resets the same starting item:

import { example } from "./setup.mjs"

for (const ReturnValues of ["NONE", "ALL_OLD", "UPDATED_OLD", "ALL_NEW", "UPDATED_NEW"]) {
  await example({ status: "draft", obsolete: true, stock: 5 }, {
    UpdateExpression: "SET #s = :s REMOVE #o",
    ExpressionAttributeNames: { "#s": "status", "#o": "obsolete" },
    ExpressionAttributeValues: { ":s": "live" },
    ReturnValues,
  }, { showReturn: true })
}
import { example } from "./setup.mjs"

for (const ReturnValues of ["NONE", "ALL_OLD", "UPDATED_OLD", "ALL_NEW", "UPDATED_NEW"]) {
  await example({ status: "draft", obsolete: true, stock: 5 }, {
    UpdateExpression: "SET #s = :s REMOVE #o",
    ExpressionAttributeNames: { "#s": "status", "#o": "obsolete" },
    ExpressionAttributeValues: { ":s": "live" },
    ReturnValues,
  }, { showReturn: true })
}

{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"NONE","returned":null}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"ALL_OLD","returned":{"obsolete":true,"pk":"item-1","status":"draft","stock":5}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"UPDATED_OLD","returned":{"obsolete":true,"status":"draft"}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"ALL_NEW","returned":{"pk":"item-1","status":"live","stock":5}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"UPDATED_NEW","returned":{"status":"live"}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"NONE","returned":null}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"ALL_OLD","returned":{"obsolete":true,"pk":"item-1","status":"draft","stock":5}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"UPDATED_OLD","returned":{"obsolete":true,"status":"draft"}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"ALL_NEW","returned":{"pk":"item-1","status":"live","stock":5}}
{"after":{"pk":"item-1","status":"live","stock":5},"before":{"obsolete":true,"pk":"item-1","status":"draft","stock":5},"mode":"UPDATED_NEW","returned":{"status":"live"}}

The fixture prints returned: null for an absent Attributes field. Notice that UPDATED_OLD includes the removed obsolete attribute, while UPDATED_NEW omits it and the untouched stock attribute. Neither option is a general-purpose record of deletions and additions; use both images in your own audit workflow if needed.

SDK v3 document client versus low-level DynamoDB JSON

Use UpdateCommand from @aws-sdk/lib-dynamodb with ordinary JavaScript values, or UpdateItemCommand from @aws-sdk/client-dynamodb with explicit type descriptors. Do not feed { N: "2" } to a document-client numeric operand: it represents a Map there. The AWS JavaScript programming guide explains the two layers and marshall/unmarshall.

Save as low-level.mjs:

import { UpdateItemCommand } from "@aws-sdk/client-dynamodb"
import { PutCommand } from "@aws-sdk/lib-dynamodb"
import { unmarshall } from "@aws-sdk/util-dynamodb"
import { low, doc, TableName, Key, read, print } from "./setup.mjs"

await doc.send(new PutCommand({ TableName, Item: { ...Key, stock: 5 } }))
const before = await read()
const result = await low.send(new UpdateItemCommand({
  TableName,
  Key: { pk: { S: "item-1" } },
  UpdateExpression: "ADD #n :n",
  ExpressionAttributeNames: { "#n": "stock" },
  ExpressionAttributeValues: { ":n": { N: "2" } },
  ReturnValues: "ALL_NEW",
}))
print({ before, after: unmarshall(result.Attributes) })
import { UpdateItemCommand } from "@aws-sdk/client-dynamodb"
import { PutCommand } from "@aws-sdk/lib-dynamodb"
import { unmarshall } from "@aws-sdk/util-dynamodb"
import { low, doc, TableName, Key, read, print } from "./setup.mjs"

await doc.send(new PutCommand({ TableName, Item: { ...Key, stock: 5 } }))
const before = await read()
const result = await low.send(new UpdateItemCommand({
  TableName,
  Key: { pk: { S: "item-1" } },
  UpdateExpression: "ADD #n :n",
  ExpressionAttributeNames: { "#n": "stock" },
  ExpressionAttributeValues: { ":n": { N: "2" } },
  ReturnValues: "ALL_NEW",
}))
print({ before, after: unmarshall(result.Attributes) })

{"after":{"pk":"item-1","stock":7},"before":{"pk":"item-1","stock":5}}
{"after":{"pk":"item-1","stock":7},"before":{"pk":"item-1","stock":5}}

Numbers on the low-level wire are strings under N. The command still increments a Number, not a String.

AWS CLI v2 example

After running setup.mjs, save this as cli.sh and run bash cli.sh. The first printed item is the strongly consistent read before the update; the second is ALL_NEW afterwards. Every call targets the local endpoint with dummy credentials.

export AWS_ACCESS_KEY_ID=fake AWS_SECRET_ACCESS_KEY=fake
export AWS_DEFAULT_REGION=us-east-1 AWS_PAGER=""
unset AWS_SESSION_TOKEN AWS_PROFILE

ddb() { aws dynamodb --endpoint-url http://localhost:8000 --region us-east-1 "$@"; }
ddb put-item --table-name UpdateExpressionDemo \
  --item '{"pk":{"S":"item-1"},"stock":{"N":"5"}}'
ddb get-item --table-name UpdateExpressionDemo \
  --key '{"pk":{"S":"item-1"}}' --consistent-read --query Item --output json
ddb update-item --table-name UpdateExpressionDemo \
  --key '{"pk":{"S":"item-1"}}' \
  --update-expression 'ADD #n :n' \
  --expression-attribute-names '{"#n":"stock"}' \
  --expression-attribute-values '{":n":{"N":"2"}}' \
  --return-values ALL_NEW --query Attributes --output json
export AWS_ACCESS_KEY_ID=fake AWS_SECRET_ACCESS_KEY=fake
export AWS_DEFAULT_REGION=us-east-1 AWS_PAGER=""
unset AWS_SESSION_TOKEN AWS_PROFILE

ddb() { aws dynamodb --endpoint-url http://localhost:8000 --region us-east-1 "$@"; }
ddb put-item --table-name UpdateExpressionDemo \
  --item '{"pk":{"S":"item-1"},"stock":{"N":"5"}}'
ddb get-item --table-name UpdateExpressionDemo \
  --key '{"pk":{"S":"item-1"}}' --consistent-read --query Item --output json
ddb update-item --table-name UpdateExpressionDemo \
  --key '{"pk":{"S":"item-1"}}' \
  --update-expression 'ADD #n :n' \
  --expression-attribute-names '{"#n":"stock"}' \
  --expression-attribute-values '{":n":{"N":"2"}}' \
  --return-values ALL_NEW --query Attributes --output json

{
    "stock": {
        "N": "5"
    },
    "pk": {
        "S": "item-1"
    }
}
{
    "stock": {
        "N": "7"
    },
    "pk": {
        "S": "item-1"
    }
}
{
    "stock": {
        "N": "5"
    },
    "pk": {
        "S": "item-1"
    }
}
{
    "stock": {
        "N": "7"
    },
    "pk": {
        "S": "item-1"
    }
}

Build an UpdateExpression dynamically from a partial object

A patch builder needs explicit meanings for omission, null and removal. These helpers treat each object key as a literal top-level attribute name. They alias every name, generate one clause per action type, reject primary-key changes, and omit ExpressionAttributeValues for remove-only patches.

These are expression builders, not schema validators. Validate types, permitted fields and expression size at your application's boundary. Pass both key names if your table has a sort key. For a nested patch, build separate aliases for explicit path segments and reject ancestor/descendant target collisions; do not split arbitrary user-supplied names on dots.

TypeScript builder

Save as builder.ts:

import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb"

export const REMOVE = Symbol("REMOVE")
type Patch = Record<string, NativeAttributeValue | typeof REMOVE | undefined>

export function buildUpdate(patch: Patch, keyNames: readonly string[] = ["pk"]) {
  const names: Record<string, string> = {}
  const values: Record<string, NativeAttributeValue> = {}
  const sets: string[] = []
  const removes: string[] = []
  for (const [name, value] of Object.entries(patch)) {
    if (value === undefined) continue
    if (!name || keyNames.includes(name)) throw new Error(`Cannot patch: ${name}`)
    const i = Object.keys(names).length
    const alias = `#n${i}`
    names[alias] = name
    if (value === REMOVE) removes.push(alias)
    else {
      const token = `:v${i}`
      sets.push(`${alias} = ${token}`)
      values[token] = value
    }
  }
  const clauses = [
    sets.length ? `SET ${sets.join(", ")}` : "",
    removes.length ? `REMOVE ${removes.join(", ")}` : "",
  ].filter(Boolean)
  if (!clauses.length) throw new Error("No changes")
  return {
    UpdateExpression: clauses.join(" "),
    ExpressionAttributeNames: names,
    ...(sets.length ? { ExpressionAttributeValues: values } : {}),
  }
}
import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb"

export const REMOVE = Symbol("REMOVE")
type Patch = Record<string, NativeAttributeValue | typeof REMOVE | undefined>

export function buildUpdate(patch: Patch, keyNames: readonly string[] = ["pk"]) {
  const names: Record<string, string> = {}
  const values: Record<string, NativeAttributeValue> = {}
  const sets: string[] = []
  const removes: string[] = []
  for (const [name, value] of Object.entries(patch)) {
    if (value === undefined) continue
    if (!name || keyNames.includes(name)) throw new Error(`Cannot patch: ${name}`)
    const i = Object.keys(names).length
    const alias = `#n${i}`
    names[alias] = name
    if (value === REMOVE) removes.push(alias)
    else {
      const token = `:v${i}`
      sets.push(`${alias} = ${token}`)
      values[token] = value
    }
  }
  const clauses = [
    sets.length ? `SET ${sets.join(", ")}` : "",
    removes.length ? `REMOVE ${removes.join(", ")}` : "",
  ].filter(Boolean)
  if (!clauses.length) throw new Error("No changes")
  return {
    UpdateExpression: clauses.join(" "),
    ExpressionAttributeNames: names,
    ...(sets.length ? { ExpressionAttributeValues: values } : {}),
  }
}

Save this as builder-demo.ts and run npx tsx builder-demo.ts:

import { buildUpdate, REMOVE } from "./builder.ts"
import { example, print } from "./setup.mjs"

const patch = buildUpdate({
  status: "live", note: null, obsolete: REMOVE,
  "audit.label": "checked", untouched: undefined,
})
print(patch)
await example({ status: "draft", obsolete: true }, patch)
await example({ obsolete: true }, buildUpdate({ obsolete: REMOVE }))
for (const invalid of [{}, { pk: "different-key" }]) {
  try { buildUpdate(invalid) }
  catch (error) { print({ error: (error as Error).message }) }
}
import { buildUpdate, REMOVE } from "./builder.ts"
import { example, print } from "./setup.mjs"

const patch = buildUpdate({
  status: "live", note: null, obsolete: REMOVE,
  "audit.label": "checked", untouched: undefined,
})
print(patch)
await example({ status: "draft", obsolete: true }, patch)
await example({ obsolete: true }, buildUpdate({ obsolete: REMOVE }))
for (const invalid of [{}, { pk: "different-key" }]) {
  try { buildUpdate(invalid) }
  catch (error) { print({ error: (error as Error).message }) }
}

{"ExpressionAttributeNames":{"#n0":"status","#n1":"note","#n2":"obsolete","#n3":"audit.label"},"ExpressionAttributeValues":{":v0":"live",":v1":null,":v3":"checked"},"UpdateExpression":"SET #n0 = :v0, #n1 = :v1, #n3 = :v3 REMOVE #n2"}
{"after":{"audit.label":"checked","note":null,"pk":"item-1","status":"live"},"before":{"obsolete":true,"pk":"item-1","status":"draft"}}
{"after":{"pk":"item-1"},"before":{"obsolete":true,"pk":"item-1"}}
{"error":"No changes"}
{"error":"Cannot patch: pk"}
{"ExpressionAttributeNames":{"#n0":"status","#n1":"note","#n2":"obsolete","#n3":"audit.label"},"ExpressionAttributeValues":{":v0":"live",":v1":null,":v3":"checked"},"UpdateExpression":"SET #n0 = :v0, #n1 = :v1, #n3 = :v3 REMOVE #n2"}
{"after":{"audit.label":"checked","note":null,"pk":"item-1","status":"live"},"before":{"obsolete":true,"pk":"item-1","status":"draft"}}
{"after":{"pk":"item-1"},"before":{"obsolete":true,"pk":"item-1"}}
{"error":"No changes"}
{"error":"Cannot patch: pk"}

The output demonstrates the literal audit.label name, stored null, an omitted undefined value, a remove-only update, and rejection of an empty patch and a primary-key change. To modify a sibling inside a Map, use a nested path as shown earlier; passing a partial Map to this helper replaces the existing Map.

Python builder with boto3 Table.update_item

Save as builder.py and run venv/bin/python builder.py after creating the table with setup.mjs. This uses boto3's resource Table.update_item, so values are native Python values. Use Decimal for non-integer numbers instead of Python float; the JSON formatter below renders non-integral Decimals as strings to avoid display precision loss.

import json
from decimal import Decimal
import boto3

REMOVE = object()


def build_update(patch, key_names=("pk",)):
    names, values, sets, removes = {}, {}, [], []
    for name, value in patch.items():
        if not isinstance(name, str) or not name or name in key_names:
            raise ValueError(f"Cannot patch: {name}")
        i = len(names)
        alias = f"#n{i}"
        names[alias] = name
        if value is REMOVE:
            removes.append(alias)
        else:
            token = f":v{i}"
            sets.append(f"{alias} = {token}")
            values[token] = value
    clauses = []
    if sets:
        clauses.append("SET " + ", ".join(sets))
    if removes:
        clauses.append("REMOVE " + ", ".join(removes))
    if not clauses:
        raise ValueError("No changes")
    result = {"UpdateExpression": " ".join(clauses), "ExpressionAttributeNames": names}
    if values:
        result["ExpressionAttributeValues"] = values
    return result


def normalize(value):
    if isinstance(value, Decimal):
        return int(value) if value == value.to_integral_value() else str(value)
    if isinstance(value, set):
        return {"$set": sorted(normalize(x) for x in value)}
    if isinstance(value, dict):
        return {k: normalize(v) for k, v in value.items()}
    if isinstance(value, list):
        return [normalize(v) for v in value]
    return value


table = boto3.resource(
    "dynamodb", endpoint_url="http://localhost:8000", region_name="us-east-1",
    aws_access_key_id="fake", aws_secret_access_key="fake",
).Table("UpdateExpressionDemo")
key = {"pk": "item-1"}

for patch in [
    {"status": "live", "note": None, "obsolete": REMOVE, "audit.label": "checked"},
    {"obsolete": REMOVE},
]:
    table.put_item(Item={**key, "status": "draft", "obsolete": True})
    before = table.get_item(Key=key, ConsistentRead=True)["Item"]
    result = table.update_item(Key=key, **build_update(patch), ReturnValues="ALL_NEW")
    print(json.dumps(normalize({"before": before, "after": result["Attributes"]}),
                     sort_keys=True, separators=(",", ":")))
for invalid in [{}, {"pk": "different-key"}]:
    try:
        build_update(invalid)
    except ValueError as error:
        print(json.dumps({"error": str(error)}, separators=(",", ":")))
import json
from decimal import Decimal
import boto3

REMOVE = object()


def build_update(patch, key_names=("pk",)):
    names, values, sets, removes = {}, {}, [], []
    for name, value in patch.items():
        if not isinstance(name, str) or not name or name in key_names:
            raise ValueError(f"Cannot patch: {name}")
        i = len(names)
        alias = f"#n{i}"
        names[alias] = name
        if value is REMOVE:
            removes.append(alias)
        else:
            token = f":v{i}"
            sets.append(f"{alias} = {token}")
            values[token] = value
    clauses = []
    if sets:
        clauses.append("SET " + ", ".join(sets))
    if removes:
        clauses.append("REMOVE " + ", ".join(removes))
    if not clauses:
        raise ValueError("No changes")
    result = {"UpdateExpression": " ".join(clauses), "ExpressionAttributeNames": names}
    if values:
        result["ExpressionAttributeValues"] = values
    return result


def normalize(value):
    if isinstance(value, Decimal):
        return int(value) if value == value.to_integral_value() else str(value)
    if isinstance(value, set):
        return {"$set": sorted(normalize(x) for x in value)}
    if isinstance(value, dict):
        return {k: normalize(v) for k, v in value.items()}
    if isinstance(value, list):
        return [normalize(v) for v in value]
    return value


table = boto3.resource(
    "dynamodb", endpoint_url="http://localhost:8000", region_name="us-east-1",
    aws_access_key_id="fake", aws_secret_access_key="fake",
).Table("UpdateExpressionDemo")
key = {"pk": "item-1"}

for patch in [
    {"status": "live", "note": None, "obsolete": REMOVE, "audit.label": "checked"},
    {"obsolete": REMOVE},
]:
    table.put_item(Item={**key, "status": "draft", "obsolete": True})
    before = table.get_item(Key=key, ConsistentRead=True)["Item"]
    result = table.update_item(Key=key, **build_update(patch), ReturnValues="ALL_NEW")
    print(json.dumps(normalize({"before": before, "after": result["Attributes"]}),
                     sort_keys=True, separators=(",", ":")))
for invalid in [{}, {"pk": "different-key"}]:
    try:
        build_update(invalid)
    except ValueError as error:
        print(json.dumps({"error": str(error)}, separators=(",", ":")))

{"after":{"audit.label":"checked","note":null,"pk":"item-1","status":"live"},"before":{"obsolete":true,"pk":"item-1","status":"draft"}}
{"after":{"pk":"item-1","status":"draft"},"before":{"obsolete":true,"pk":"item-1","status":"draft"}}
{"error":"No changes"}
{"error":"Cannot patch: pk"}
{"after":{"audit.label":"checked","note":null,"pk":"item-1","status":"live"},"before":{"obsolete":true,"pk":"item-1","status":"draft"}}
{"after":{"pk":"item-1","status":"draft"},"before":{"obsolete":true,"pk":"item-1","status":"draft"}}
{"error":"No changes"}
{"error":"Cannot patch: pk"}

Python has no JavaScript-style undefined; omit a dictionary key to leave the attribute unchanged. None writes NULL, and only the sentinel requests removal.

Common UpdateExpression errors and their fixes

The following messages were reproduced from DynamoDB Local. Each failing request below started and ended with exactly {"pk":"item-1"}; no requested change was applied. The ValidationException prefix is the exception name. SDK wrappers may format their surrounding message differently.

Two document paths overlap

ValidationException: Invalid UpdateExpression: Two document paths overlap with each other; must remove or rewrite one of these paths; path one: [profile], path two: [profile, city]
ValidationException: Invalid UpdateExpression: Two document paths overlap with each other; must remove or rewrite one of these paths; path one: [profile], path two: [profile, city]

The failing expression was SET #p = :p, #p.#c = :c, with #p mapped to profile and #c to city. Set the whole Map once, or update only its children when the Map already exists. Parent initialization and child updates must be separate requests.

The document path is invalid for update

ValidationException: The document path provided in the update expression is invalid for update
ValidationException: The document path provided in the update expression is invalid for update

SET #p.#c = :c failed because profile was absent. Initialize the Map separately as shown below. An existing parent of the wrong type also needs correction.

Invalid UpdateExpression: Syntax error

ValidationException: Invalid UpdateExpression: Syntax error; token: "<EOF>", near: "="
ValidationException: Invalid UpdateExpression: Syntax error; token: "<EOF>", near: "="

The incomplete expression SET #s = has no operand. Supply a value token and its mapping, as in the upsert example. Also check commas and parentheses.

Attribute name is a reserved keyword

ValidationException: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status
ValidationException: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status

The failing expression used SET status = :s. Change it to SET #s = :s with ExpressionAttributeNames mapping #s to status.

The SET section can only be used once

ValidationException: Invalid UpdateExpression: The "SET" section can only be used once in an update expression;
ValidationException: Invalid UpdateExpression: The "SET" section can only be used once in an update expression;

SET #s = :s SET #n = :n repeats the clause keyword. Use SET #s = :s, #n = :n instead.

An expression attribute value is not defined

ValidationException: Invalid UpdateExpression: An expression attribute value used in expression is not defined; attribute value: :missing
ValidationException: Invalid UpdateExpression: An expression attribute value used in expression is not defined; attribute value: :missing

SET #s = :missing used an unmapped token. Add :missing to ExpressionAttributeValues, or correct the expression to use the token you actually supplied.

The expression refers to an attribute that does not exist

ValidationException: The provided expression refers to an attribute that does not exist in the item
ValidationException: The provided expression refers to an attribute that does not exist in the item

SET #l = list_append(#l, :new) failed with no items attribute. Use if_not_exists(#l, :empty) with an empty List, as in lists.mjs. An existing non-List value needs a type correction instead.

Cannot update a primary-key attribute

ValidationException: One or more parameter values were invalid: Cannot update attribute pk. This attribute is part of the key
ValidationException: One or more parameter values were invalid: Cannot update attribute pk. This attribute is part of the key

SET #pk = :pk tried to change pk. The key belongs in Key, not among the update targets. Moving an item to another key requires creating the new item and deleting the old one, with a transaction if they must succeed together.

An empty set is invalid

ValidationException: ExpressionAttributeValues contains invalid value: One or more parameter values were invalid: An string set  may not be empty for key :empty
ValidationException: ExpressionAttributeValues contains invalid value: One or more parameter values were invalid: An string set  may not be empty for key :empty

This exact message came from a low-level ADD #t :empty request with :empty set to SS: []. An empty JavaScript Set can instead fail earlier during marshalling. Omit an empty union/subtraction operation, or use REMOVE to delete the entire stored Set. Do not convert an empty Set to NULL unless that type change is intended.

Fix a missing parent map

Create the parent as part of the original item whenever possible. For existing data with an optional parent, initialize it with if_not_exists in one request, then update the child in another. Save as fix-parent.mjs; the fixture shows the state transition for each request:

import { example } from "./setup.mjs"

// Seed a missing map, without replacing an existing one.
const initialized = await example({}, {
  UpdateExpression: "SET #p = if_not_exists(#p, :empty)",
  ExpressionAttributeNames: { "#p": "profile" },
  ExpressionAttributeValues: { ":empty": {} },
})
await example(initialized, {
  UpdateExpression: "SET #p.#c = :c",
  ExpressionAttributeNames: { "#p": "profile", "#c": "city" },
  ExpressionAttributeValues: { ":c": "Rome" },
})
import { example } from "./setup.mjs"

// Seed a missing map, without replacing an existing one.
const initialized = await example({}, {
  UpdateExpression: "SET #p = if_not_exists(#p, :empty)",
  ExpressionAttributeNames: { "#p": "profile" },
  ExpressionAttributeValues: { ":empty": {} },
})
await example(initialized, {
  UpdateExpression: "SET #p.#c = :c",
  ExpressionAttributeNames: { "#p": "profile", "#c": "city" },
  ExpressionAttributeValues: { ":c": "Rome" },
})

{"after":{"pk":"item-1","profile":{}},"before":{"pk":"item-1"}}
{"after":{"pk":"item-1","profile":{"city":"Rome"}},"before":{"pk":"item-1","profile":{}}}
{"after":{"pk":"item-1","profile":{}},"before":{"pk":"item-1"}}
{"after":{"pk":"item-1","profile":{"city":"Rome"}},"before":{"pk":"item-1","profile":{}}}

Those are two operations, not one atomic unit. A concurrent writer can change or remove the map between them; add an appropriate condition and handle failure, or enforce the map's presence in your item schema. Trying to combine parent initialization and child assignment in one expression still produces the overlap error. If replacing the whole Map is intended, assign the complete Map once.

How update writes are billed

Updating one small attribute does not mean paying only for that attribute. DynamoDB uses the larger item size before or after an UpdateItem, rounded up in 1 KB units. A change from a 2.2 KB item to a 2.3 KB item therefore uses three ordinary write units; deleting attributes from 2.3 KB down to 0.8 KB still uses three for that operation. A transactional write uses twice the ordinary units. Index maintenance can add write consumption.

Failed conditions can also consume write capacity. Returning attributes does not add a read-capacity charge. AWS documents this in read and write operation accounting. Use ReturnConsumedCapacity: "INDEXES" to observe table and index consumption on service requests; DynamoDB Local is not a production billing benchmark.

Expression and item limits

These are fixed constraints in the AWS constraints reference and document-path rules. The token limit does not cap a stored String value at 255 bytes. The operator limit covers condition, filter and update expressions; assignment = inside SET does not count, while arithmetic, functions and condition comparisons do. A generated patch must fit all applicable limits.

Can DynamoDB update many items with one expression?

An UpdateExpression addresses one item. DynamoDB has no arbitrary multi-item UPDATE ... WHERE operation. Even PartiQL UPDATE must resolve to one primary key.

BatchWriteItem supports puts and deletes, not updates. The batch write and update guide covers those differences. Use transactions when partial completion would break an invariant; do not include two actions for the same item in one transaction. The batch statement API and transaction API specify these boundaries.

For an occasional manual correction, Dynobase bulk editing provides bulk edits, undo and item history without writing a custom patch script.

When finished with the examples, stop the disposable container with docker stop dynamodb-local; its in-memory table disappears.