Injecting Chaos into DynamoDB with LocalStack
Chaos engineering is a methodology that helps build more resilient cloud-based applications. In this tutorial, learn how to simulate outages using LocalStack's Chaos Dashboard. This hands-on guide walks through injecting failure into a local AWS stack, observing how your app responds, and building confidence in your system's ability to handle the unexpected.

Resilient apps aren’t just built. They’re tested under pressure. That’s where chaos engineering comes in. In this walkthrough, we’ll explore what chaos engineering is, show you how to simulate outages using the LocalStack Chaos Dashboard, using a .NET app and DynamoDB.
You’ll learn how to inject faults, see how your app handles failure, and start building cloud-native apps that can take a hit.
What Even Is Chaos Engineering?
Chaos engineering is about proactively testing your system’s resilience by introducing failures in a controlled way with the goal of preventing these failures from becoming significant outages.
Instead of waiting for an outage in production, you simulate one on your terms using an experiment and observe how the system reacts. The goal is to answer questions like:
- What happens if a service your app is dependent on fails?
- Will users see an error message or just a blank screen?
- Can the system recover on its own, or does it need help?
LocalStack provides a perfect laboratory for conducting chaos experiments without impacting your production or staging environments, meaning you can improve your application’s resilience without any risk of actual outages. Let’s see how.
What You’ll Learn
- How to connect a simple .NET app to DynamoDB
- How to simulate a DynamoDB outage using LocalStack’s Chaos Dashboard
- How the app reacts to the chaos and what to watch for
What You’ll Need
- .NET SDK
- AWS SDK for .NET (
AWSSDK.DynamoDBv2
NuGet package) - Docker
- LocalStack Ultimate (there’s a free trial)
- Your LocalStack auth token
Clone the Sample App
We’re using a basic console app that writes to and reads from a DynamoDB table. You can grab it here:
GitHub Repo – C# Chaos Demo
The app:
- Creates a
Products
table if it doesn’t exist - Inserts an item using
PutItemAsync
- Reads the item using
GetItemAsync
- Logs any errors that come up
Step 1: Set Up the AWS SDK
Configure the AWS SDK to talk to LocalStack instead of real AWS.
var config = new AmazonDynamoDBConfig{ ServiceURL = "http://localhost:4566", UseHttp = true};var credentials = new BasicAWSCredentials("test", "test");var client = new AmazonDynamoDBClient(credentials, config);
Step 2: Create the DynamoDB Table (If Needed)
Before inserting data, the app checks whether the Products
table exists. If it doesn’t, it creates the table with a simple hash key (Id
).
const string tableName = "Products";
var tables = await client.ListTablesAsync();if (!tables.TableNames.Contains(tableName)){ Console.WriteLine("Creating table...");
var createRequest = new CreateTableRequest { TableName = tableName, KeySchema = new List<KeySchemaElement> { new KeySchemaElement("Id", KeyType.HASH) }, AttributeDefinitions = new List<AttributeDefinition> { new AttributeDefinition("Id", ScalarAttributeType.S) }, ProvisionedThroughput = new ProvisionedThroughput { ReadCapacityUnits = 5, WriteCapacityUnits = 5 } };
await client.CreateTableAsync(createRequest);}
This sets up the table structure with a string-based primary key so we can store and retrieve product items easily during testing.
Step 3: Insert a Sample Item
Now that the table exists, insert a test item into the Products
table. This helps us verify that DynamoDB is working as expected before chaos is introduced.
var putRequest = new PutItemRequest{ TableName = tableName, Item = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { S = "123" } }, { "Name", new AttributeValue { S = "Chaos Widget" } }, { "Price", new AttributeValue { N = "49.99" } } }};
await client.PutItemAsync(putRequest);
Later, when the DynamoDB Error experiment is active in the Chaos Dashboard, this call should fail. That’s a good thing—it gives you a clear opportunity to test how your app reacts to service disruptions.
Step 4: Try to Read the Item
After inserting the item, use GetItemAsync
to read it back from the Products
table. This step verifies that the item was successfully stored and retrieved under normal conditions.
var getRequest = new GetItemRequest{ TableName = tableName, Key = new Dictionary<string, AttributeValue> { { "Id", new AttributeValue { S = "123" } } }};
var getResponse = await client.GetItemAsync(getRequest);
This should fail too once chaos is active, which is exactly what we want to observe.
Step 5: Catch and Log Failures
Let’s add some simple logging to identify the errors when they occur.
catch (AmazonDynamoDBException ex){ Console.WriteLine("AWS SDK Exception caught!"); Console.WriteLine($"Status Code: {ex.StatusCode}"); Console.WriteLine($"Error Code: {ex.ErrorCode}"); Console.WriteLine($"Message: {ex.Message}");}
This helps surface when and how the app breaks.
Step 6: Run LocalStack and Launch Chaos
Next let’s get the application deployed to LocalStack. In this example, we’ll use a docker-compose.yml
file:
version: '3.8'services: localstack: image: localstack/localstack-pro container_name: localstack ports: - "4566:4566" - "443:443" environment: - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} volumes: - ./localstack:/var/lib/localstack
As the chaos functionality is part of LocalStack’s paid tier, we’ll need to provide a license key, so let’s create a .env
file with our key:
LOCALSTACK_AUTH_TOKEN=your-token-here
Now start LocalStack up:
docker compose up
Then go to the Chaos Dashboard and start the DynamoDB Error experiment.
Run the App and Observe
Run your app:
dotnet run
You should start seeing the errors roll in. That’s your app under stress.
Head back to the dashboard to stop the experiment and bring things back to normal. If this were a real app, this is when you’d start making adjustments to ensure the errors you see here wouldn’t cause a serious incident and outage, but, for now, we’ll be content just observing the behavior.
Final Thoughts
Chaos engineering is about building confidence. By simulating outages in DynamoDB, you can see how your app handles failure and find the spots that need hardening. Start small. Break things in a safe space. Use what you learn to build stronger systems. Try this out with your own stack using LocalStack. It gives you a safe, local environment to run experiments like this without racking up cloud costs or taking down real infrastructure. Chaos engineering and the Chaos API are part of LocalStack’s Ultimate tier. You can try it out for free by starting a free trial. Got questions or want to share your results? Drop a comment in the GitHub repo or tag us @localstack on BlueSky. We’d love to see what you’re breaking (and fixing).