Injecting Chaos into DynamoDB with LocalStack

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