Error: Error ValidationException: One or more parameter values were invalid: Type mismatch for key X expected: S actual: M

Type mismatch for key X expected: S actual: M means key X is defined as a String but the request contains a Map. A common cause is sending low-level DynamoDB JSON to a document client that marshals it again.

With DynamoDBDocumentClient, X: { S: "abc" } is a JavaScript object and becomes a DynamoDB Map. Pass X: "abc" instead:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}));

await db.send(new PutCommand({
  TableName: "Records",
  Item: { X: "abc", description: "Example" },
}));

For the low-level DynamoDBClient and PutItemCommand, the typed form Item: { X: { S: "abc" } } is correct. Use one serialization layer, not both. In boto3, resource Table methods accept native Python values, while client methods take AttributeValue dictionaries.

1. Read AttributeDefinitions and KeySchema from DescribeTable, including any indexes referenced by the failing write.
2. Check the value immediately before sending it. A nested object, an ORM wrapper or a second marshalling pass can turn a string into a map.
3. Keep the key scalar. If a business object contains the key, extract its string identifier and store the rest as a separate map attribute.

DynamoDB is flexible about non-key attributes, but it enforces declared table and index key types. Do not recreate a table merely to accommodate an incorrectly serialized request.

See DynamoDB JSON conversion and AWS documentation.