Introduction

When DynamoDB Local runs in Docker but list-tables returns nothing, the problem is usually endpoint targeting, container networking, or data persistence location. The DynamoDB process can be healthy while the client points to a different instance. This guide walks through a reproducible setup and the checks that usually resolve the issue quickly.

Run DynamoDB Local in Docker

Start a container with explicit port mapping and a persistent volume.

1docker run --rm --name dynamodb-local \
2  -p 8000:8000 \
3  -v "$PWD/dynamodb-data:/home/dynamodblocal/data" \
4  amazon/dynamodb-local \
5  -jar DynamoDBLocal.jar -sharedDb -dbPath /home/dynamodblocal/data

The -sharedDb option simplifies local development because all credentials map to one local database file.

Use Correct AWS CLI Endpoint

Without --endpoint-url, AWS CLI talks to cloud DynamoDB, not your local container.

aws dynamodb list-tables \
  --endpoint-url http://localhost:8000 \
  --region us-east-1

Create a test table and list again:

1aws dynamodb create-table \
2  --table-name Users \
3  --attribute-definitions AttributeName=UserId,AttributeType=S \
4  --key-schema AttributeName=UserId,KeyType=HASH \
5  --billing-mode PAY_PER_REQUEST \
6  --endpoint-url http://localhost:8000 \
7  --region us-east-1
8
9aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-east-1

If table creation succeeds but listing still appears empty, you are likely hitting different endpoints across commands.

Verify Container Health and Port Mapping

Confirm container status and mapped ports.

docker ps --filter "name=dynamodb-local"
docker logs dynamodb-local | tail -n 20

If port mapping changed, update your client endpoint. If container restarts frequently, check Docker logs for file permission issues on mounted volume paths.

Diagnose Networking from Another Container

If your app runs in another container, localhost inside that container points to itself, not DynamoDB Local.

Use Docker network names instead:

# Example endpoint from another container in same network
http://dynamodb-local:8000

In docker-compose, set both services on one network and reference service name as host.

Check Persistence and Data Location

If tables disappear after restart, data is not persisted. Mount a host folder and pass -dbPath to keep state.

Also ensure your local shell is not mixing in-memory mode in one run and file-backed mode in another. That creates confusing behavior where tables seem to vanish.

Reproducible Local Setup with Compose

Using docker-compose reduces command drift across team members and CI environments. A simple service definition keeps port mapping and startup options consistent.

1services:
2  dynamodb-local:
3    image: amazon/dynamodb-local
4    command: "-jar DynamoDBLocal.jar -sharedDb -dbPath /home/dynamodblocal/data"
5    ports:
6      - "8000:8000"
7    volumes:
8      - ./dynamodb-data:/home/dynamodblocal/data

After startup, run table operations against http://localhost:8000. Keep helper scripts in the repository for create-table and list-tables commands so everyone uses identical endpoints. Standardizing setup removes many false troubleshooting paths caused by per-machine command differences.

CLI Profile Isolation

Use a dedicated local AWS CLI profile to avoid accidental credential and region crossover from cloud profiles. Local profile scripts with explicit endpoint and region values make commands repeatable and safer for daily development. This also prevents confusion when environment variables override your expected settings.

Common Pitfalls

A common pitfall is forgetting --endpoint-url on one command. You create tables locally, then list in cloud account, or the reverse.

Another issue is running multiple local instances on different ports and connecting to the wrong one from scripts.

Developers also assume localhost works from all containers. In containerized apps, use service hostnames on shared networks.

A final problem is no persistent volume mapping, so tables disappear on restart and listing appears empty unexpectedly.

Summary

• Ensure Docker container runs with expected port mapping and optional persistent volume.
• Always pass local DynamoDB endpoint in CLI commands.
• Verify container logs and health when listing fails.
• Use service hostnames for container-to-container communication.
• Keep runtime mode consistent between sessions to avoid data confusion.