This error occurs when DynamoDB Local starts but cannot load the AWS SDK for Node.js library. It typically indicates missing dependencies, incorrect Node.js versions, or misconfigurations with AWS SDK v2 vs v3 compatibility.
The "DynamoDB Local: Unable to load the AWS SDK for Node.js" error indicates that the DynamoDB Local instance has started successfully, but when your Node.js application attempts to connect to it, the AWS SDK library is either not installed, not properly configured, or incompatible with your Node.js version and AWS SDK version. This is a common issue when: - **AWS SDK v2 to v3 migration**: You've upgraded to AWS SDK v3 but are still using old v2-style imports or configurations - **Missing dependencies**: The AWS SDK package is not installed or the specific client module is missing - **Node.js version incompatibility**: Using Node.js 18+ with outdated SDK configurations or deprecated module paths - **IPv6 vs IPv4 conflicts**: Node.js 18+ prefers IPv6 (::1) for localhost, but DynamoDB Local listens on IPv4 (127.0.0.1) - **Connection configuration**: Missing endpoint URL or invalid credentials configuration - **Environment setup**: DynamoDB Local is running but application can't establish connection due to missing credentials The error message itself is somewhat generic and can mask several underlying issues. Proper diagnosis requires checking your application's SDK imports, version compatibility, and connection configuration.
First, ensure DynamoDB Local is actually running and accessible on port 8000:
Using Docker:
docker run -d --name dynamodb-local -p 8000:8000 amazon/dynamodb-localUsing JAR file:
java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDbUsing local-dynamo npm package:
npm install -g local-dynamo
local-dynamoVerify it's accessible:
curl http://127.0.0.1:8000/
# or
curl http://localhost:8000/You should get a response (likely empty or an error page, but not a connection refused).
Make sure you have the required AWS SDK v3 packages installed:
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodbVerify installation:
npm ls @aws-sdk/client-dynamodb
npm ls @aws-sdk/lib-dynamodbIf upgrading from SDK v2, you can remove the old package:
npm uninstall aws-sdk
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodbCheck your package.json has these entries:
{
"dependencies": {
"@aws-sdk/client-dynamodb": "^3.x.x",
"@aws-sdk/lib-dynamodb": "^3.x.x"
}
}If you're migrating from AWS SDK v2, update your import statements:
OLD (AWS SDK v2):
const AWS = require('aws-sdk');
const dynamodb = new AWS.DynamoDB({
region: 'local',
endpoint: 'http://localhost:8000'
});NEW (AWS SDK v3):
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
const client = new DynamoDBClient({
region: 'local',
endpoint: 'http://localhost:8000'
});
const docClient = DynamoDBDocumentClient.from(client);TypeScript version:
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
const dynamoDBClient = new DynamoDBClient({
region: 'local',
endpoint: 'http://localhost:8000',
});
const docClient = DynamoDBDocumentClient.from(dynamoDBClient);DynamoDB Local requires credentials to be configured, even though they won't be validated. Add fake credentials to your configuration:
In your Node.js code:
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({
region: 'local',
endpoint: 'http://localhost:8000',
credentials: {
accessKeyId: 'dummy',
secretAccessKey: 'dummy'
}
});Or use environment variables:
.env
AWS_ACCESS_KEY_ID=dummy
AWS_SECRET_ACCESS_KEY=dummy
AWS_REGION=localThen reference them:
const client = new DynamoDBClient({
region: process.env.AWS_REGION || 'local',
endpoint: 'http://localhost:8000',
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID || 'dummy',
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || 'dummy'
}
});Node.js 18 and newer prefer IPv6 (::1) for localhost, but DynamoDB Local listens on IPv4 (127.0.0.1). Use the explicit IP address:
PROBLEMATIC (may fail on Node.js 18+):
const client = new DynamoDBClient({
endpoint: 'http://localhost:8000'
});CORRECT (works on all Node.js versions):
const client = new DynamoDBClient({
endpoint: 'http://127.0.0.1:8000'
});Alternative: Force IPv4 resolution:
const client = new DynamoDBClient({
endpoint: 'http://localhost:8000',
// Add custom fetch with IPv4 preference
});Create a test file to verify your SDK can connect to DynamoDB Local:
// test-dynamodb.js
import { DynamoDBClient, ListTablesCommand } from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({
region: 'local',
endpoint: 'http://127.0.0.1:8000',
credentials: {
accessKeyId: 'dummy',
secretAccessKey: 'dummy'
}
});
async function testConnection() {
try {
const command = new ListTablesCommand({});
const response = await client.send(command);
console.log('✓ Connection successful!');
console.log('Tables:', response.TableNames || []);
} catch (error) {
console.error('✗ Connection failed:', error.message);
process.exit(1);
}
}
testConnection();Run the test:
node test-dynamodb.jsIf successful, you'll see "Connection successful!" and a list of tables.
Verify you're using compatible versions:
# Check Node.js version
node --version
# Check AWS SDK v3 version
npm ls @aws-sdk/client-dynamodb
# Check if aws-sdk v2 is still installed
npm ls aws-sdkRecommended versions:
- Node.js: 16.x or higher (18+ requires IPv4 fix above)
- AWS SDK v3: 3.100.0 or higher
- AWS SDK v2: Deprecated, avoid for new projects
If aws-sdk v2 is still installed alongside v3:
npm uninstall aws-sdk
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm ciIf you're having issues with DynamoDB commands, use the DocumentClient wrapper:
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, GetCommand, PutCommand } from '@aws-sdk/lib-dynamodb';
const client = new DynamoDBClient({
region: 'local',
endpoint: 'http://127.0.0.1:8000',
credentials: {
accessKeyId: 'dummy',
secretAccessKey: 'dummy'
}
});
const docClient = DynamoDBDocumentClient.from(client);
// Now use docClient with native JavaScript objects
const putCommand = new PutCommand({
TableName: 'Users',
Item: {
id: '123',
name: 'John'
}
});
await docClient.send(putCommand);DocumentClient automatically converts between JavaScript objects and DynamoDB format, reducing errors.
Create a dedicated file for your DynamoDB connection to avoid configuration issues:
// src/lib/dynamodb.js
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
const isLocal = process.env.NODE_ENV === 'development' || process.env.DYNAMODB_LOCAL === 'true';
const clientConfig = {
region: process.env.AWS_REGION || 'us-east-1',
...(isLocal && {
endpoint: 'http://127.0.0.1:8000',
credentials: {
accessKeyId: 'dummy',
secretAccessKey: 'dummy'
}
})
};
const client = new DynamoDBClient(clientConfig);
const docClient = DynamoDBDocumentClient.from(client);
export { client, docClient };Then use it throughout your app:
import { docClient } from './lib/dynamodb.js';
import { GetCommand } from '@aws-sdk/lib-dynamodb';
const result = await docClient.send(new GetCommand({
TableName: 'Users',
Key: { id: '123' }
}));Migration from AWS SDK v2 to v3:
The AWS SDK v2 has reached end-of-support. If you're seeing this error during a v2-to-v3 migration, pay careful attention to:
1. Module paths changed: v2 used aws-sdk or aws-sdk/clients/dynamodb, v3 uses modular packages like @aws-sdk/client-dynamodb
2. Client initialization: v2 used new AWS.DynamoDB(), v3 uses new DynamoDBClient()
3. Commands: v3 uses explicit command objects (GetCommand, PutCommand) instead of method calls
4. Promises: v3 uses native Promises; v2 used callbacks or special Promise patterns
Docker Compose setup for local development:
version: '3.8'
services:
dynamodb-local:
image: amazon/dynamodb-local
ports:
- '8000:8000'
volumes:
- ./data:/home/dynamodblocal/data
environment:
AWS_ACCESS_KEY_ID: dummy
AWS_SECRET_ACCESS_KEY: dummy
AWS_DEFAULT_REGION: localDebugging connection issues:
If you're still getting the error after following the steps above:
// Enable AWS SDK debug logging
process.env.AWS_SDK_LOG_DEST = process.stdout;
process.env.AWS_SDK_LOG = 'debug';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({
region: 'local',
endpoint: 'http://127.0.0.1:8000',
credentials: {
accessKeyId: 'dummy',
secretAccessKey: 'dummy'
},
// Add retries for connection issues
maxAttempts: 3
});Common mistakes that cause this error:
1. Running npm install without clearing cache after removing v2: npm cache clean --force && npm install
2. Having both v2 and v3 installed simultaneously - causes module resolution confusion
3. Using http://localhost without a port number - must be http://127.0.0.1:8000
4. Forgetting to add credentials configuration - the SDK won't initialize without them
5. Running DynamoDB Local in a Docker container but not exposing port 8000 correctly
ImportConflictException: There was a conflict when attempting to import to the table
How to fix 'ImportConflictException: There was a conflict when attempting to import to the table' in DynamoDB
ResourceNotFoundException: Requested resource not found
How to fix "ResourceNotFoundException: Requested resource not found" in DynamoDB
TrimmedDataAccessException: The requested data has been trimmed
How to fix "TrimmedDataAccessException: The requested data has been trimmed" in DynamoDB Streams
GlobalTableNotFoundException: Global Table not found
How to fix "GlobalTableNotFoundException: Global Table not found" in DynamoDB
InvalidExportTimeException: The specified ExportTime is outside of the point in time recovery window
How to fix "InvalidExportTimeException: The specified ExportTime is outside of the point in time recovery window" in DynamoDB