How to fix ValidationException: One or more parameter values were invalid in DynamoDB

ValidationException: One or more parameter values were invalid: An AttributeValue may not contain an empty string
ValidationException: One or more parameter values were invalid: Type mismatch for key userId expected: S actual: M
ValidationException: One or more parameter values were invalid: Missing the key userId in the item
ValidationException: One or more parameter values were invalid: Condition parameter type does not match schema type

// ❌ WRONG - This will cause ValidationException
const item = {
  userId: { S: '123' },
  email: { S: '' }, // Empty string not allowed
};

// ✅ CORRECT - Option 1: Remove the empty attribute
const item = {
  userId: { S: '123' },
  // email omitted if empty
};

// ✅ CORRECT - Option 2: Use null/NULL for missing data
const item = {
  userId: { S: '123' },
  email: { NULL: true },
};

// ✅ CORRECT - Option 3: With DocumentClient, enable convertEmptyValues
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';

const client = new DynamoDBClient({ region: 'us-east-1' });
const docClient = DynamoDBDocumentClient.from(client, {
  marshallOptions: {
    convertEmptyValues: true, // Converts empty strings to NULL
    removeUndefinedValues: true, // Removes undefined fields
  }
});

const item = {
  userId: '123',
  email: '', // Will be converted to NULL
};

await docClient.send(new PutCommand({
  TableName: 'Users',
  Item: item
}));

// ❌ WRONG - Type mismatch error
// Schema defines userId as String (S), but you're sending a Map (M)
const item = {
  userId: { M: { value: { S: '123' } } }, // Wrong!
};

// ✅ CORRECT - Use the right type
const item = {
  userId: { S: '123' }, // String type
};

// For numeric attributes, use Number string format
const item2 = {
  age: { N: '25' }, // Must be string representation of number
};

// With DocumentClient (easier)
const docClient = DynamoDBDocumentClient.from(client);
const item3 = {
  userId: '123', // String
  age: 25, // Number (automatically converted to N)
  isActive: true, // Boolean (automatically converted to BOOL)
  tags: ['tag1', 'tag2'], // List (automatically converted to L)
  metadata: { key: 'value' }, // Map (automatically converted to M)
};

await docClient.send(new PutCommand({
  TableName: 'Users',
  Item: item3
}));

// ❌ WRONG - Missing partition key
const item = {
  email: { S: '[email protected]' },
  // userId missing! This is the partition key
};

// ✅ CORRECT - Include all required keys
const item = {
  userId: { S: '123' }, // Partition key required
  sortKey: { S: 'user#profile' }, // Sort key required if table has one
  email: { S: '[email protected]' },
};

// Check your table schema to identify required keys
const table = await dynamodb.describeTable({
  TableName: 'Users'
});

console.log('Keys:', table.Table.KeySchema);
// Output example: [
//   { AttributeName: 'userId', KeyType: 'HASH' },     // Partition key
//   { AttributeName: 'sortKey', KeyType: 'RANGE' }    // Sort key (if present)
// ]

// For Put operations, always include all keys
await docClient.send(new PutCommand({
  TableName: 'Users',
  Item: {
    userId: '123', // Partition key - REQUIRED
    sortKey: 'profile', // Sort key - REQUIRED if defined in schema
    email: '[email protected]'
  }
}));

// For Query operations, partition key is required in Key
await docClient.send(new QueryCommand({
  TableName: 'Users',
  KeyConditionExpression: 'userId = :userId', // Partition key required
  ExpressionAttributeValues: {
    ':userId': '123'
  }
}));

// ❌ WRONG - Invalid UpdateExpression syntax
await docClient.send(new UpdateCommand({
  TableName: 'Users',
  Key: { userId: '123' },
  UpdateExpression: 'SET email [email protected]', // Wrong syntax
}));

// ✅ CORRECT - Use proper UpdateExpression syntax
await docClient.send(new UpdateCommand({
  TableName: 'Users',
  Key: { userId: '123' },
  UpdateExpression: 'SET email = :email',
  ExpressionAttributeValues: {
    ':email': '[email protected]'
  }
}));

// ❌ WRONG - Type mismatch in ConditionExpression
await docClient.send(new UpdateCommand({
  TableName: 'Users',
  Key: { userId: '123' },
  ConditionExpression: 'attribute_exists(userId) AND age > "25"', // age is number, comparing with string
  UpdateExpression: 'SET email = :email',
  ExpressionAttributeValues: {
    ':email': '[email protected]'
  }
}));

// ✅ CORRECT - Proper type comparison
await docClient.send(new UpdateCommand({
  TableName: 'Users',
  Key: { userId: '123' },
  ConditionExpression: 'attribute_exists(userId) AND age > :minAge',
  ExpressionAttributeValues: {
    ':minAge': 25, // Same type as age attribute
    ':email': '[email protected]'
  },
  UpdateExpression: 'SET email = :email'
}));

// Common expression rules:
// 1. Use placeholders for values: :value or #name
// 2. Attribute names: Use ExpressionAttributeNames if name is reserved
// 3. Values: Use ExpressionAttributeValues for all dynamic values
// 4. Type consistency: Ensure compared values have matching types

# View complete table schema
aws dynamodb describe-table --table-name Users

# Check key schema
aws dynamodb describe-table --table-name Users \
  --query 'Table.{KeySchema: KeySchema, AttributeDefinitions: AttributeDefinitions}'

# Output example:
# {
#   "KeySchema": [
#     {"AttributeName": "userId", "KeyType": "HASH"},
#     {"AttributeName": "sortKey", "KeyType": "RANGE"}
#   ],
#   "AttributeDefinitions": [
#     {"AttributeName": "userId", "AttributeType": "S"},
#     {"AttributeName": "sortKey", "AttributeType": "S"}
#   ]
# }

// Verify in code before operations
const table = await dynamodb.describeTable({ TableName: 'Users' });
const keySchema = table.Table.KeySchema;
const attributeDefs = table.Table.AttributeDefinitions;

console.log('Required keys:', keySchema.map(k => k.AttributeName));
console.log('Attribute types:', attributeDefs.reduce((acc, attr) => {
  acc[attr.AttributeName] = attr.AttributeType;
  return acc;
}, {}));