> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikopod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reproduce

> Turn a recorded production failure into a scenario that recreates it against the sandbox, on your laptop.

You cannot ask a provider's sandbox to return that exact 503, with that body, at that point in your state machine. pikopod can, because the same tool recorded it and owns the sandbox.

```bash theme={null}
pikopod agent incidents                              # find the fingerprint
pikopod reproduce fp_14835fa32dfb
```

```text theme={null}
reproduced fp_14835fa32dfb (examplepay answered 503 on POST /charges) as pikopod-data/scenarios/incident-14835fa32dfb.yaml
PASSED — 1 assertion(s) passed; 0 not evaluated
the failure now happens locally — fix it, then re-run: pikopod scenario check examplepay incident-14835fa32dfb
```

## What the pack does

`reproduce` writes an ordinary scenario pack with three steps:

1. A `NOTE` carrying the provenance: which incident, when it was first seen, and what was reconstructed.
2. An `INJECT_FAULT` that arms the same failure on the same method and path template, once, then recovers. A 5xx or 4xx becomes an `error` with that status, answering with the recorded response body when the provider sent JSON. A 429 becomes `rate_limit`. An unreachable upstream becomes a `connection_reset`, because reproducing it as a 502 would test the wrong branch of your error handling.
3. A `REQUEST` that replays the recorded request and asserts the recorded status.

The pack then runs immediately against the sandbox named by the incident's upstream, or `--sandbox <name>`.

```bash theme={null}
pikopod scenario check examplepay incident-14835fa32dfb
```

```text theme={null}
✓ incident-14835fa32dfb — PASSED (1 assertion(s) passed; 0 not evaluated)
    PASSED         context          incident fp_14835fa32dfb: examplepay answered 503 on POST /charges, first seen 2026-09-18T10:00:00Z. This request was RECONSTRUCTED from a redacted recording…
    NOT_EVALUATED  arm-failure      armed error on POST /charges
    PASSED         replay           POST /charges → 503
```

Commit the pack and it guards that path forever, with no recording needed.

## The honest limit

Requests and responses are rebuilt from **redacted** recordings. Identifiers are format-preserving tokens and anything the sanitizer could not classify was dropped before it reached disk, so neither body is byte-identical. Error codes and spec-declared enum values survive redaction, so the armed response body still carries what your code switches on. Every generated pack says so in its note.

* For a 5xx, a 429 or an unreachable upstream this changes nothing: the fault is armed on method and path, so the failure reproduces regardless.
* For a 4xx your own payload caused, the request body matters. If the pack does not reproduce the rejection, compare it against what your code actually sends.

## Exit codes

`reproduce` exits `0` when it writes a pack and the failure recurs, and `2` when it refuses: the recording aged out of retention, or the pack ran and the failure did **not** recur, which means pikopod cannot stand behind it as a reproduction. It never fabricates a request to avoid refusing. There is no exit `1`. See [Exit codes](https://docs.pikopod.com/operations/exit-codes.md#reproduce-has-no-exit-1).

## From another machine

When the agent runs on a host that is not your laptop, export the incident and reproduce from the file:

```bash theme={null}
pikopod agent incidents export fp_14835fa32dfb > incident.json     # on the agent host
pikopod reproduce ./incident.json                    # anywhere
pikopod agent incidents import ./incident.json       # and keep behaving that way
```

`import` installs the incident locally: the event, a rule that answers as the provider did, and the resource the recording touched, so `reproduce <fingerprint>` lands on the seeded resource and the sandbox keeps the failure after the pack has run. See [Incident bundles](https://docs.pikopod.com/reproduce/incident-bundles.md).

## Shape changes

For a shape change rather than a failure, `from-drift` pins the old contract instead. See [Generated packs](https://docs.pikopod.com/scenarios/generated-packs.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.