DEV Community

Cover image for Your Error Survived the Wrapper. Did Its Code Survive the Trace?

Your Error Survived the Wrapper. Did Its Code Survive the Trace?

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",
});
Enter fullscreen mode Exit fullscreen mode

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");
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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.

Application error identity is preserved on both paths, while the tested manual and instance writers preserve different diagnostic fields.

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:

  1. Successful return values remain unchanged.
  2. Thrown application errors remain unchanged.
  3. Required bounded diagnostic fields survive readback.
  4. 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

Top comments (0)