Suppose an instrumented operation throws an error with code: "ETIMEDOUT". Your application catches that exact object. Its retry policy behaves correctly.
Later, an engineer opens the persisted trace. The message is present. The code is missing.
Both observations can be true. Preserving application behavior and preserving diagnostic evidence are different compatibility contracts.
I maintain AgentInspect. While preparing this article, I tested both contracts against 6.31.35. The result is worth explaining because it includes a current limitation: the manual wrapper and instance-based writer paths do not persist identical error fields.
Test behavior before inspecting serialization
First create one synthetic error object:
const original = Object.assign(new Error("Synthetic timeout"), {
code: "ETIMEDOUT",
});
Then assert that instrumentation rethrows that same object:
import assert from "node:assert/strict";
import { inspectRun, step } from "agent-inspect";
let caught;
try {
await inspectRun("manual-error", () =>
step.tool("read_policy", async () => { throw original; }),
{ traceDir: ".agent-inspect", silent: true },
);
} catch (error) {
caught = error;
}
assert.strictEqual(caught, original);
assert.equal(caught.code, "ETIMEDOUT");
That is a stronger assertion than comparing messages. Application code may inspect the error's class, code, cause, or object identity. A wrapper that throws a newly constructed error could change those behaviors even if its message looks reasonable.
This fixture verifies identity for the tested path. It does not yet say what was written to disk.
Cross the serialization boundary explicitly
Now compare an instance-based capture using a file writer:
import { createInspector } from "agent-inspect";
import { fileWriter } from "agent-inspect/writers";
const inspector = createInspector({
writer: fileWriter({ filePath: "./instance-error.jsonl" }),
});
let instanceCaught;
try {
await inspector.run("instance-error", () =>
inspector.tool("read_policy", async () => { throw original; }),
);
} catch (error) {
instanceCaught = error;
} finally {
await inspector.flush();
await inspector.close();
}
assert.strictEqual(instanceCaught, original);
Use isolated paths when testing so a previous run cannot satisfy a later assertion accidentally. The companion harness creates fresh temporary directories, reads the generated rows, and checks the persisted error field rather than relying on terminal output.
The observed comparison is:
| Tested property | Manual inspectRun() / step()
|
createInspector() + fileWriter()
|
|---|---|---|
| Original error object rethrown | Yes | Yes |
| Persisted schema in this test | 0.1 |
1.0 |
| Synthetic message retained | Yes | Yes |
error.code retains ETIMEDOUT
|
No | Yes |
These are release-specific test results, not an assertion that every adapter uses one of these paths in the same way.
Compatibility needs a behavioral test and a persisted-evidence test.
Why the missing field matters
If an offline report groups failures by error code, the manual trace cannot supply the code that was never persisted. A reader should not reconstruct it by guessing from prose.
Messages are unstable. They can change with dependency versions, localization, nested causes, and remote-service responses. They may also contain sensitive values. Treating a message as a machine-readable classification creates both reliability and privacy problems.
Conversely, the presence of ETIMEDOUT does not establish whether a remote operation committed before the timeout. The code describes an observed error category; it is not an effect receipt.
Decide which fields your debugging and policy workflows actually require, then verify their survival through capture, serialization, readback, and any export you use.
Don’t solve fidelity by dumping the error object
A quick serialization fix might copy every enumerable property from an SDK error. That can bring request headers, response bodies, internal URLs, or credentials into the trace.
Prefer a reviewed allowlist of bounded fields. For an application-owned error model, that might be a stable category and a sanitized code. Keep unknown fields out until there is a concrete need and a data-handling decision.
The instance serializer's code support is not a promise to retain arbitrary nested error data. Nor should arbitrary retention be the goal. Fidelity means preserving the evidence your contract needs, not maximizing the bytes captured.
If a field is unavailable in the chosen capture path, the article, report, and release gate should say so. A missing classification is better labeled unknown than inferred incorrectly.
A small compatibility matrix beats a broad promise
For each integration path your team supports, test four things:
- Successful return values remain unchanged.
- Thrown application errors remain unchanged.
- Required bounded diagnostic fields survive readback.
- Instrumentation failures do not replace application results.
Run the matrix against the installed release, not only imports from a source checkout. Serialization code, package exports, and adapter wiring can differ from what a unit test exercises internally.
Keep a negative fixture, too: add a synthetic sensitive field and verify that it is not accidentally persisted. Do this with fake values, not production credentials. The right field list is an explicit design choice.
Know which contract you are claiming
The claim “the wrapper preserves errors” is incomplete until you say which boundary you mean.
For the tested release, both paths preserve the thrown object. Only the tested instance path preserves the synthetic error code in persisted rows. That does not invalidate the first property; it means the second property needs separate attention.
Before building an error taxonomy from traces, inspect a tiny fixture containing one known code. It is cheaper to discover a missing field there than after a report has classified every timeout as “unknown.”
Implementation references
- Manual capture path
- Instance implementation
- Persisted schema documentation
- Companion:
examples/probes.test.mjs, testD05.

Top comments (2)
Great breakdown of the gap between runtime error identity and persisted trace fidelity. It is surprisingly easy for an instrumentation wrapper to pass behavioral retry tests on
error.codewhile silently dropping that exact field during serialization, which usually only surfaces later when offline reports lump real timeouts into "unknown" or push teams into parsing brittle error messages.The point about avoiding a naive full-object dump and verifying an explicit allowlist with a negative fixture for sensitive fields is especially practical. Separating those two contracts upfront saves a lot of silent observability debt.
In agentdiet 0.11, 94 % of CI integrations consume
--jsonrather than text, so the CLI's output contract — including error codes — is part of the agent's effective capability, not just the model. A missingerror.codein the trace means 94 % of automated consumers lose the classification they rely on for retry policies and alerting.