How to fix DynamoDB Local: Unable to load the AWS SDK for Node.js in DynamoDB

DynamoDBINTERMEDIATEMEDIUMUpdated Dec 29, 2025· 186 views

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.

Quick fix

Fixes DynamoDB Local: Unable to load the AWS SDK for Node.js

docker run -d --name dynamodb-local -p 8000:8000 amazon/dynamodb-local
  1. Verify DynamoDB Local is running
  2. Install the correct AWS SDK v3 packages
  3. Update SDK imports to v3 syntax
  4. Add fake credentials for local development
dynamodb — error
docker run -d --name dynamodb-local -p 8000:8000 amazon/dynamodb-local
DynamoDB Local: Unable to load the AWS SDK for Node.js

What this error means

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.

Typical symptoms

  • DynamoDB Local starts successfully but application fails to connect
  • Error message appears when calling AWS SDK methods
  • Import statements for AWS SDK fail or return undefined
  • Connection timeout when trying to reach http://localhost:8000
  • SDK operations fail even though DynamoDB Local is running
  • Works with SDK v2 but fails after upgrading to SDK v3
  • Connection succeeds on Node.js 16 but fails on Node.js 18+

Common causes

  1. AWS SDK package is not installed (missing npm install @aws-sdk/client-dynamodb)
  2. Using deprecated AWS SDK v2 with old module paths (aws-sdk/clients/dynamodb)
  3. Node.js version 18+ preferring IPv6 (::1) while DynamoDB Local listens on IPv4
  4. Missing credentials configuration - AWS SDK requires credentials even for local testing
  5. Incorrect endpoint URL configuration
  6. DynamoDB Local not running or not accessible on the configured port
  7. Port conflict - another service is using port 8000
  8. Missing DynamoDBDocumentClient wrapper when using SDK v3
  9. Firewall or network rules blocking localhost connection

How to fix "DynamoDB Local: Unable to load the AWS SDK for Node.js"

1Verify DynamoDB Local is running

First, ensure DynamoDB Local is actually running and accessible on port 8000:

Using Docker:

bash
docker run -d --name dynamodb-local -p 8000:8000 amazon/dynamodb-local

Using JAR file:

bash
java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

Using local-dynamo npm package:

bash
npm install -g local-dynamo
local-dynamo

Verify it's accessible:

bash
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).

2Install the correct AWS SDK v3 packages

Make sure you have the required AWS SDK v3 packages installed:

bash
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Verify installation:

bash
npm ls @aws-sdk/client-dynamodb
npm ls @aws-sdk/lib-dynamodb

If upgrading from SDK v2, you can remove the old package:

bash
npm uninstall aws-sdk
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Check your package.json has these entries:

json
{
  "dependencies": {
    "@aws-sdk/client-dynamodb": "^3.x.x",
    "@aws-sdk/lib-dynamodb": "^3.x.x"
  }
}
3Update SDK imports to v3 syntax

If you're migrating from AWS SDK v2, update your import statements:

OLD (AWS SDK v2):

javascript
const AWS = require('aws-sdk');
const dynamodb = new AWS.DynamoDB({
  region: 'local',
  endpoint: 'http://localhost:8000'
});

NEW (AWS SDK v3):

javascript
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:

typescript
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);
4Add fake credentials for local development

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:

javascript
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:

bash
.env
AWS_ACCESS_KEY_ID=dummy
AWS_SECRET_ACCESS_KEY=dummy
AWS_REGION=local

Then reference them:

javascript
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'
  }
});
5Use IP address instead of localhost for Node.js 18+

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+):

javascript
const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000'
});

CORRECT (works on all Node.js versions):

javascript
const client = new DynamoDBClient({
  endpoint: 'http://127.0.0.1:8000'
});

Alternative: Force IPv4 resolution:

javascript
const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  // Add custom fetch with IPv4 preference
});
6Test connection with a simple script

Create a test file to verify your SDK can connect to DynamoDB Local:

javascript
// 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:

bash
node test-dynamodb.js

If successful, you'll see "Connection successful!" and a list of tables.

7Check Node.js and SDK version compatibility

Verify you're using compatible versions:

bash
# 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-sdk

Recommended 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:

bash
npm uninstall aws-sdk
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm ci
8Use DynamoDBDocumentClient for easier JSON handling

If you're having issues with DynamoDB commands, use the DocumentClient wrapper:

javascript
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.

9Create a reusable connection utility

Create a dedicated file for your DynamoDB connection to avoid configuration issues:

javascript
// 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:

javascript
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' }
}));

Advanced notes

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:

yaml
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: local

Debugging connection issues:

If you're still getting the error after following the steps above:

javascript
// 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

Frequently asked questions

What does "DynamoDB Local: Unable to load the AWS SDK for Node.js" mean?
js version and AWS SDK version. 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.
How do I fix "DynamoDB Local: Unable to load the AWS SDK for Node.js"?
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.
What causes "DynamoDB Local: Unable to load the AWS SDK for Node.js"?
AWS SDK package is not installed (missing npm install @aws-sdk/client-dynamodb) Using deprecated AWS SDK v2 with old module paths (aws-sdk/clients/dynamodb) Node.js version 18+ preferring IPv6 (::1) while DynamoDB Local listens on IPv4
Is the "DynamoDB Local: Unable to load the AWS SDK for Node.js" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading