Intermediate8 min read

How to Connect to DynamoDB Local and LocalStack

You have a local DynamoDB running and your code talks to it fine, but you want to see the tables instead of writing a scan script every time. Connecting a client to a local endpoint is two changes: point at the right URL, and hand it throwaway credentials.

The details below are where people get stuck: region namespacing, the alphanumeric-key rule, and the 8000 vs 4566 port split.

DynamoDB Local vs LocalStack: what you're connecting to

Both give you a DynamoDB API on localhost with no AWS account (LocalStack needs a LocalStack account, see below), but they're different things:

  • DynamoDB Local is the downloadable DynamoDB engine in a single process. AWS ships it as a JAR and a Docker image (amazon/dynamodb-local). It's DynamoDB and nothing else. Default port 8000 (AWS docs). See running DynamoDB Local with Docker.
  • LocalStack emulates a stack of AWS services behind one endpoint. Its DynamoDB is itself powered by DynamoDB Local, but every service goes through LocalStack's single port 4566. Since release 2026.03.0 the localstack/localstack image won't start without a LocalStack auth token (LOCALSTACK_AUTH_TOKEN), so you need a LocalStack account. Its free Hobby plan is for non-commercial use; commercial use needs a paid plan (pricing). If you only need DynamoDB, DynamoDB Local is free and needs no account.

So the practical difference for connecting is the endpoint URL: :8000 for standalone DynamoDB Local, :4566 for DynamoDB-via-LocalStack. The API and the credentials trick are the same.

To browse local tables in a grid instead of reading DynamoDB-JSON on the CLI, DynoTable connects with an Offline profile: a port and a Region, no keys to enter (setup).

Endpoint and dummy credentials

The AWS SDKs and CLI require an access key and a region even when talking to a local endpoint, but those values don't have to be real. AWS's own docs say these values "don't have to be valid AWS values to run locally" (AWS docs).

  • The region/access-key silently namespaces your data. Without the -sharedDb flag, DynamoDB Local keeps a separate database per access-key ID + region, in a file named myaccesskeyid_region.db (AWS's exact naming).

    The split holds in memory too: on DynamoDB Local 3.3.1 started with -inMemory, a table created with key x in local was invisible to key dummy in us-east-1. Connect with a different key or region than your app used and your tables look like they've vanished.

    The fix: start DynamoDB Local with -sharedDb (one shared-local-instance.db for every client), or use the exact key + region your app uses. On LocalStack, which keeps a separate database per credential and region too, start the container with DYNAMODB_SHARE_DB=1.

  • The access key ID must be alphanumeric on DynamoDB Local, no symbols. AWS docs state AWS_ACCESS_KEY_ID can contain only A–Z, a–z, and 0–9; AWS introduced this in DynamoDB Local 2.0.0 (and 1.23.0+), so a key with special characters that worked on an earlier image now fails (AWS re:Post). See the error below.

For LocalStack the safe default is test / test: it ignores the secret key entirely and never validates the secret value. Real-looking AKIA…/ASIA… keys are rejected as a safeguard and fall back to the dummy account 000000000000, the same account an arbitrary key like test resolves to. Stick with test.

Connecting with the AWS CLI (sanity check)

Before pointing a GUI at it, confirm the endpoint is alive from the CLI. The CLI has no built-in default local endpoint, so either pass --endpoint-url per command or set AWS_ENDPOINT_URL_DYNAMODB=http://localhost:8000 (CLI v2.13+).

DynamoDB Local:

aws dynamodb list-tables --endpoint-url http://localhost:8000

LocalStack (same command, different port):

aws dynamodb list-tables --endpoint-url http://localhost:4566

If you have credentials configured at all (even fake ones in ~/.aws/credentials or via AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), this returns your table list. An empty list with no error means the endpoint works but you're looking at a different key/region namespace (see the gotcha above).

DynamoDB Local GUI: browsing and querying local tables in DynoTable

Once the CLI works, start the engine so every client shares one database. DynoTable signs local requests with its own fixed throwaway key, so it only sees your app's tables when the engine doesn't split them by key:

# DynamoDB Local: override the image's default command to add -sharedDb
docker run -p 8000:8000 amazon/dynamodb-local -jar DynamoDBLocal.jar -inMemory -sharedDb

# LocalStack: one shared DynamoDB database (needs your LocalStack auth token)
docker run -p 4566:4566 -e LOCALSTACK_AUTH_TOKEN=<token> -e DYNAMODB_SHARE_DB=1 localstack/localstack

Then add a profile in DynoTable:

  • Profile type: Offline.
  • Port: 8000 (DynamoDB Local) or 4566 (LocalStack). The profile always connects to http://localhost:<port>.
  • AWS Region: pick the region your app uses from the list, e.g. us-east-1. On DynamoDB Local with -sharedDb any entry works; on LocalStack, match your app's region.

There is no access-key field; the profile supplies its own alphanumeric throwaway key. From there you browse items, run a Query or Scan, and edit items instead of JSON by hand on the CLI.

When you load fixtures, the DynamoDB-JSON converter turns plain JSON into the wire format, and Query vs Scan covers which read to reach for. DynoTable is local-only desktop software, so pointing it at localhost keeps your fixtures on your machine. For a broader look at the GUI options, see the DynamoDB GUI comparison.

Common errors (region mismatch, port, credentials)

  • Connection refused. Wrong port: 8000 is DynamoDB Local, 4566 is LocalStack. Also confirm the container actually published the port (docker run -p 8000:8000 amazon/dynamodb-local). For LocalStack, check the service is up at http://localhost:4566/_localstack/health, and that you passed LOCALSTACK_AUTH_TOKEN: without it the container doesn't start (docker logs says why).
  • The Access Key ID or security token is invalid. on DynamoDB Local. Since the 2.0.0 (and 1.23.0+) image, the access key ID must be alphanumeric only. A key with symbols that worked on an earlier image now fails. Replace it with letters/numbers (e.g. test) and update every tool to match.
  • The security token included in the request is invalid against LocalStack. This is almost always an endpoint problem, not a credentials one: your SDK client dropped the --endpoint-url / endpoint_url and hit the real AWS endpoint, which rejects your dummy key. Confirm the client is actually pointed at http://localhost:4566.
  • Credential errors from the SDK/CLI. Even local endpoints need some credentials present. Set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or a fake profile) so the SDK's credential chain resolves.
  • http vs https. DynamoDB Local speaks plain http, so an https:// URL fails the TLS handshake. LocalStack accepts both http://localhost:4566 and https://localhost.localstack.cloud:4566, for which it publishes a certificate.

Is DynamoDB Local the same data as my real AWS tables?

No. Local and cloud are completely separate stores. DynamoDB Local (and LocalStack's DynamoDB) keeps data in a local file or in memory; it never touches your AWS account, and AWS Regions/accounts aren't supported at the client level locally. That's the point: it's for development and testing.

AWS suggests valid-looking key/region values locally so your code only needs the endpoint swapped when you move. The data stays behind: to seed a cloud table, rerun your fixture loader against the real endpoint (BatchWriteItem, 25 items per call).

To model that schema before you ship it, single-table design and GSI vs LSI cover the decisions that don't change between local and prod.

What local saves you (and what prod still bills)

Local reports consumed capacity per request but bills nothing and never throttles; the cloud bills every read and write. When to leave Local covers what that hides. Model the jump with the pricing calculator and size representative items with the item-size calculator.

FAQ

Do I need real AWS credentials? No. Both DynamoDB Local and LocalStack accept dummy values. They just have to be present, alphanumeric (for DynamoDB Local), and consistent across your tools, unless the engine runs one shared database. LocalStack does need its own auth token to start; DynamoDB Local needs nothing.

Why do my tables disappear when I switch tools? Without -sharedDb, DynamoDB Local keeps one database per access key + region. See the namespacing gotcha.

What's the difference between port 8000 and 4566? 8000 is standalone DynamoDB Local's default; 4566 is LocalStack's single port that fronts all its emulated services, DynamoDB included.

Is DynamoDB Local free? Yes. AWS distributes DynamoDB Local at no cost as a JAR and a Docker image, with "no provisioned throughput, data storage, or data transfer costs"; it's intended for development and testing only, not production.

Can I run SQL against my local tables? Local DynamoDB speaks the same API as the cloud, so the same access-pattern rules apply, and the same limits: DynamoDB's PartiQL SELECT grammar is SELECT … FROM … WHERE … ORDER BY only, with no JOIN, no GROUP BY, and no grouping aggregate functions like COUNT/SUM/AVG (see PartiQL vs SQL). DynoTable's runs those analytical queries over any connection, local included.

Try DynoTable: start the engine with one shared database (-sharedDb or DYNAMODB_SHARE_DB=1, as above), add an Offline profile on port 8000 or 4566, and browse, query, and edit your local tables with a GUI.

By Dmitriy · Updated