The Fine Art of a Minimal Reproducible Example

Two hours in, what you're actually shipping is a GitHub issue, a JIRA ticket, or a Slack thread: symptoms, hunches, pasted logs, then one more file because someone asked nicely. Each round trip tugs another detail out of your repo while the runnable version still lives mostly on your machine. Then a follow-up makes you spell out the repro steps you sort of skipped the first time, and halfway through your reply the bug stops looking fuzzy. Nobody merged a fix for you. You just finally described it clearly enough to see it yourself.

That loop is about as expensive as debugging gets, and almost none of it is mandatory. The antidote is the minimal reproducible example (MRE): the smallest, most self-contained piece of code that reliably triggers the problem you're trying to explain. Being kind to whoever reads your ticket is a nice side effect. The main payoff is that your own picture of the break gets sharper. Most of the time you'll see the answer yourself before you hit send.

A Diagnostic Trilogy¶

An MRE has exactly three properties. Violate any one of them and you no longer have an MRE: you have either a code dump or a non-starter.

Minimal¶

Strip the code down to the smallest case that still triggers the issue. Remove authentication helpers, logging setup, database connections, unrelated configuration, and everything else that isn't directly involved in the failure. If you can delete a line and the bug still occurs, delete it.

This is harder than it sounds when you're deep in a problem. Everything feels relevant. It's not. The act of removing code is itself a debugging act: each deletion either moves you closer to the root cause or proves that section of code isn't involved.

Reproducible¶

The example must trigger the same behavior every time, in any environment, for anyone who runs it. "It only happens on my machine" isn't an MRE: it's still a hypothesis. Track down the conditions that consistently trigger the issue and make those conditions explicit in the example.

Your example shouldn't depend on:

• External services that require credentials or network access
• Files or state that exist only on your machine
• Configuration loaded from environment variables that aren't shown
• A sequence of prior steps that must be completed first

If external state is genuinely part of the problem, substitute the smallest possible local stand-in: a hardcoded string, an in-memory mock, or a local test fixture.

Example¶

An example is a program that runs. Not a fragment, not a diff, not pseudocode: a complete, standalone piece of code that anyone can paste into a clean environment and execute immediately. Include imports. Include dependency versions. Include the invocation. Remove every reason for someone to say "I can't run this."

The Debug That Happens Before You Ask¶

Creating an MRE is a more reliable debugging technique than most developers give it credit for. The process forces you to form and test hypotheses. You delete a block and the problem disappears: that block was involved. You delete a different block and the problem persists: that block isn't. You replace a library call with a direct implementation and the behavior changes: the issue was in the library, not your code.

This is the rubber duck effect scaled up and made systematic. Explaining a problem to an inanimate object forces clear articulation, and clear articulation surfaces the gaps in your reasoning. Constructing an MRE does the same thing, but with code instead of words.

Building One: The Process in Four Steps¶

Start from a blank file. Not a copy of your project with things deleted: a new file from scratch. Rebuild only what is necessary to trigger the issue. This discipline prevents you from dragging irrelevant code along through the back door.

Add the minimum until it fails. Introduce just enough structure to trigger the behavior. Run it after each addition. Stop adding the moment the issue appears.

Remove everything that isn't the bug. Go the other direction. Delete functions, variables, imports, and configuration blocks one at a time. Run after each removal. If removing something makes the issue disappear, put it back. Everything else goes.

Pin and document your environment. Record the exact versions of every tool and dependency involved. What looks like a logic bug can be a version regression. If you're not sure whether version matters, include it anyway: let the person helping you decide.

Five Examples Across Languages and Tools¶

Each example below shows the same pattern: a production scenario with too much noise to diagnose cleanly, then the MRE that isolates the exact issue. Skim the "Before" tab for the friction, then watch what stripping away the extras reveals.

package main

import (
    "database/sql"
    "fmt"
    "log"
    "net/http"
    "sync"
    "time"

    _ "github.com/lib/pq"
)

type Task struct {
    ID   int
    Name string
}

func fetchTasks(db *sql.DB) []Task {
    // ... 40 lines of query logic ...
    return []Task{{ID: 1, Name: "alpha"}, {ID: 2, Name: "beta"}, {ID: 3, Name: "gamma"}}
}

func processTask(t Task, client *http.Client, logger *log.Logger) error {
    // ... 80 lines of HTTP calls, retries, metrics ...
    logger.Printf("processing task %d: %s", t.ID, t.Name)
    return nil
}

func main() {
    db, _ := sql.Open("postgres", "host=localhost dbname=tasks")
    client := &http.Client{Timeout: 10 * time.Second}
    logger := log.Default()

    tasks := fetchTasks(db)

    var wg sync.WaitGroup
    for _, t := range tasks {
        wg.Add(1)
        go func() {
            defer wg.Done()
            if err := processTask(t, client, logger); err != nil {
                logger.Printf("error: %v", err)
            }
        }()
    }
    wg.Wait()
}

package main

import (
    "fmt"
    "sync"
)

func main() {
    items := []string{"alpha", "beta", "gamma"}

    var wg sync.WaitGroup
    for _, item := range items {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fmt.Println(item)
        }()
    }
    wg.Wait()
}

gamma
gamma
gamma

for _, item := range items {
    wg.Add(1)
    go func(i string) {
        defer wg.Done()
        fmt.Println(i)
    }(item)
}

import csv
import logging
from typing import Optional

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


def load_config(path: str) -> dict:
    # ... config loading logic ...
    return {"output_dir": "/tmp/results", "batch_size": 100}


def process_row(row: dict, config: dict) -> Optional[dict]:
    # ... validation, transformation, enrichment ...
    if row.get("active") == "true":
        return {"id": row["id"], "name": row["name"]}
    return None


def append_result(result: dict, accumulator: list = []) -> list:
    accumulator.append(result)
    return accumulator


def run_pipeline(input_file: str) -> None:
    config = load_config("config.yaml")
    results = []
    with open(input_file) as f:
        reader = csv.DictReader(f)
        for row in reader:
            processed = process_row(row, config)
            if processed:
                results = append_result(processed)
    logger.info("Collected %d results", len(results))


if __name__ == "__main__":
    run_pipeline("data_batch_1.csv")
    run_pipeline("data_batch_2.csv")

def append_result(result: dict, accumulator: list = []) -> list:
    accumulator.append(result)
    return accumulator


print(append_result({"id": 1}))
print(append_result({"id": 2}))
print(append_result({"id": 3}))

[{'id': 1}]
[{'id': 1}, {'id': 2}]
[{'id': 1}, {'id': 2}, {'id': 3}]

def append_result(result: dict, accumulator: list | None = None) -> list:
    if accumulator is None:
        accumulator = []
    accumulator.append(result)
    return accumulator

# main.tf (condensed from a 600-line multi-module configuration)

module "network" {
  source     = "./modules/network"
  datacenter = var.datacenter
  # ...
}

module "storage" {
  source    = "./modules/storage"
  datastore = var.datastore
  # ...
}

resource "vsphere_virtual_machine" "app_server" {
  name             = "app-server-01"
  resource_pool_id = data.vsphere_compute_cluster.cluster.resource_pool_id
  datastore_id     = module.storage.datastore_id
  num_cpus         = 4
  memory           = 8192
  guest_id         = data.vsphere_virtual_machine.template.guest_id
  firmware         = data.vsphere_virtual_machine.template.firmware

  network_interface {
    network_id = module.network.portgroup_id
  }

  disk {
    label = "disk0"
    size  = data.vsphere_virtual_machine.template.disks.0.size
  }

  clone {
    template_uuid = data.vsphere_virtual_machine.template.id

    customize {
      linux_options {
        host_name = "app-server-01"
        domain    = var.domain
      }
      network_interface {}
    }
  }
}

terraform {
  required_providers {
    vsphere = {
      source  = "hashicorp/vsphere"
      version = "~> 2.11"
    }
  }
}

provider "vsphere" {
  vsphere_server       = var.vsphere_server
  user                 = var.vsphere_user
  password             = var.vsphere_password
  allow_unverified_ssl = true
}

data "vsphere_datacenter" "dc" {
  name = "dc-01"
}

data "vsphere_datastore" "ds" {
  name          = "datastore-01"
  datacenter_id = data.vsphere_datacenter.dc.id
}

data "vsphere_compute_cluster" "cluster" {
  name          = "cluster-01"
  datacenter_id = data.vsphere_datacenter.dc.id
}

data "vsphere_network" "network" {
  name          = "VM Network"
  datacenter_id = data.vsphere_datacenter.dc.id
}

data "vsphere_virtual_machine" "template" {
  name          = "ubuntu-22.04-template"
  datacenter_id = data.vsphere_datacenter.dc.id
}

resource "vsphere_virtual_machine" "vm" {
  name             = "mre-test-vm"
  resource_pool_id = data.vsphere_compute_cluster.cluster.resource_pool_id
  datastore_id     = data.vsphere_datastore.ds.id
  num_cpus         = 2
  memory           = 2048
  guest_id         = data.vsphere_virtual_machine.template.guest_id
  firmware         = data.vsphere_virtual_machine.template.firmware

  network_interface {
    network_id = data.vsphere_network.network.id
  }

  disk {
    label = "disk0"
    size  = data.vsphere_virtual_machine.template.disks.0.size
  }

  clone {
    template_uuid = data.vsphere_virtual_machine.template.id

    customize {
      linux_options {
        host_name = "mre-test-vm"
        domain    = "example.com"
      }
      network_interface {}
    }
  }
}

variable "vsphere_server"   { type = string }
variable "vsphere_user"     { type = string }
variable "vsphere_password" {
  type      = string
  sensitive = true
}

Error: error cloning virtual machine: error reconfiguring virtual machine:
ServerFaultCode: A general system error occurred: Customization of the guest operating
system 'ubuntu64Guest' is not supported in this configuration.

param (
    [string]$VIServer = "vcenter.example.com",
    [string]$Cluster  = "Production",
    [string]$Prefix   = "web-"
)

Import-Module VMware.PowerCLI

function Write-AuditLog {
    param([string]$Message)
    Add-Content -Path "C:\audit\powercli.log" -Value "$(Get-Date) $Message"
}

Connect-VIServer -Server $VIServer -Credential (Get-Credential)

$cluster = Get-Cluster -Name $Cluster
$vms     = Get-VM -Location $cluster | Where-Object { $_.Name -like $Prefix }

foreach ($vm in $vms) {
    Write-AuditLog "Processing: $($vm.Name)"
    # ... 60 more lines ...
}

Disconnect-VIServer -Server $VIServer -Confirm:$false

$names  = @("web-01", "web-02", "app-01", "db-01")
$prefix = "web-"

$matched = $names | Where-Object { $_ -like $prefix }
Write-Output "Matched count: $($matched.Count)"

Matched count: 0

"web-01" -like "web-"   # False: matches the literal string only
"web-01" -like "web-*"  # True: * matches any suffix

# site.yml
- name: Deploy application
  hosts: app_servers
  vars_files:
    - group_vars/all.yml
    - group_vars/staging.yml
  roles:
    - role: common
    - role: app_config
    - role: app_deploy
    - role: monitoring

# group_vars/staging.yml
app_env: ""

# roles/app_config/tasks/main.yml
- name: Show resolved environment
  ansible.builtin.debug:
    msg: "Deploying to: {{ app_env | default('production') }}"

- name: MRE for default filter with empty string
  hosts: localhost
  gather_facts: false
  vars:
    app_env: ""
  tasks:
    - name: Show environment with default filter
      ansible.builtin.debug:
        msg: "Deploying to: {{ app_env | default('production') }}"

ansible-playbook mre.yml -i localhost,

TASK [Show environment with default filter] ***
ok: [localhost] => {
    "msg": "Deploying to: "
}

msg: "Deploying to: {{ app_env | default('production', true) }}"

TASK [Show environment with default filter] ***
ok: [localhost] => {
    "msg": "Deploying to: production"
}

What to Include Alongside the Code¶

A runnable example without context is still an incomplete MRE. The code answers "what happens"; you also need to supply "what I expected to happen" and the environment in which it happened.

Include the following alongside any MRE:

Version Reference by Tool

Common Mistakes¶

After you've built a few MREs, you notice a rhythm: you sit down to ask for help, and somewhere around the third deletion the story tells itself. Strip a dependency and the bug vanishes. Pin a version and the behavior shifts. Swap a library call for something tiny and obvious, and you suddenly see what the abstraction was hiding.

The MRE habit nudges you into real understanding before you outsource the thinking. Most bugs don't do well under that kind of light.

When an MRE doesn't crack the case alone, it still shrinks the gap between "I've got a bug" and "someone else gets my bug" from hours to minutes.

That's the quiet gift: you've already mapped the boundary so everyone can spend time fixing, not doing archaeology.