Debugging Interviews: Start With a Failing Contract, Not a Clever Guess

#career #interview #javascript #backend

Repository-based debugging interviews are rarely testing whether you can guess the bug from a log line. They are testing whether you can reduce uncertainty without breaking the thing you are trying to fix. A small failing contract, one observable boundary, and one deliberately boring test will usually beat a fast theory.

I use one rule when practicing these rounds: do not start by proposing a fix. Start by stating what must become true when the function returns.

For example, imagine a profile update endpoint that sometimes appears to hang. It has already validated the input. The next question is not “what is wrong with the database?” It is: does this request always settle as success or a useful failure?

That is a contract we can test.

What is the smallest contract worth reproducing?

The reproduction below injects the persistence dependency instead of requiring a server, a database, or a full repository checkout. One implementation resolves immediately. The other never settles. The service has a 25 ms deadline in the test so the failure becomes an observable error rather than a test suite that simply stalls.

Save this as debugging-contract-demo.mjs and run node debugging-contract-demo.mjs.

import assert from "node:assert/strict";

function withTimeout(promise, ms, label) {
  let timer;
  const deadline = new Promise((_, reject) => {
    timer = setTimeout(
      () => reject(`${label} timed out after ${ms}ms`),
      ms,
    );
  });

  return Promise.race([promise, deadline]).finally(() => clearTimeout(timer));
}

function createProfileService({ save, timeoutMs = 50 }) {
  return {
    async updateEmail(userId, email) {
      if (!email.includes("@")) throw new Error("email is invalid");

      await withTimeout(save({ userId, email }), timeoutMs, "profile save");
      return { ok: true };
    },
  };
}

const fastSave = async (record) => record;
const stuckSave = () => new Promise(() => {});

const healthy = createProfileService({ save: fastSave });
assert.deepEqual(
  await healthy.updateEmail("u_42", "me@example.com"),
  { ok: true },
);

const unhealthy = createProfileService({
  save: stuckSave,
  timeoutMs: 25,
});
await assert.rejects(
  () => unhealthy.updateEmail("u_42", "me@example.com"),
  /profile save timed out after 25ms/,
);

console.log("passed: success and timeout contracts hold");

The expected output is:

passed: success and timeout contracts hold

This is intentionally not a production timeout recipe. A real deadline needs to fit the dependency, the request budget, retries, cancellation, and the user experience. The useful part is the boundary: a dependency that never resolves is no longer indistinguishable from a slow request.

Why is this a better first move than reading every file?

Because it separates a symptom from an explanation.

Before the reproduction, “the update hangs” could mean a dead database connection, an unawaited callback, a lock, a swallowed rejection, a test double with the wrong shape, or a client that disconnected. After the reproduction, we have a much narrower statement:

Given a persistence operation that never settles, the profile service must reject by its deadline.

That statement is useful even if the eventual root cause is elsewhere. It gives you an invariant to preserve while you inspect logs and trace the real implementation.

It also makes the next debugging steps less performative:

Reproduce. Isolate the smallest input and dependency behavior that demonstrates the failure.
Observe. Put timing or structured logs at the boundary, not everywhere. Record the request ID, dependency name, elapsed time, and outcome.
Hypothesize. Name one causal claim that the evidence could disprove: “the save promise is waiting on a connection pool checkout.”
Patch. Change the smallest thing that should make the contract true. Avoid bundling a refactor with the diagnosis.
Verify. Run the original reproduction, then the adjacent success case. A timeout test alone is not enough if the healthy path stopped working.

The diagram is deliberately linear, but real work is not. You may loop from observation back to reproduction three times. What matters is that each loop produces new evidence.

How would I explain this in an interview?

A strong debugging answer has a surprisingly small shape. It does not need a dramatic outage story.

Try this sequence:

“I first defined the observable failure: the update must settle rather than leave the caller waiting. I built a small reproduction by injecting a persistence function that never resolves. That ruled out most UI and routing noise. I added timing at the service boundary, used the result to test the connection-pool hypothesis, then added a bounded failure path and verified both a successful save and the timeout case.”

That answer names a contract, an experiment, an observation point, a falsifiable hypothesis, and a regression test. It is much stronger than “I checked the logs and fixed the timeout,” even when the eventual code change is only a few lines.

Interviewers often follow with one of these questions:

Follow-up	What a useful answer covers
“Why not retry?”	Retrying a request that may have written data can duplicate side effects. Define idempotency and ownership before adding retries.
“Why is a timeout safe?”	A timeout stops waiting; it does not prove the downstream work stopped. Pair it with cancellation where the dependency supports it and make the outcome visible.
“What would you log?”	A correlation ID, dependency operation, elapsed time, retry count, and safe identifiers. Never dump credentials or whole request bodies.
“How would you roll this out?”	Start with metrics and an alert for the existing symptom, ship the smallest change, and watch both timeout rate and successful completion rate.

Notice that none of these answers require inventing a number. If you have a real metric, use it. If you do not, be precise about the signal you would measure.

What usually goes wrong in a debugging exercise?

The common failure mode is treating the first plausible explanation as the diagnosis. “It is probably a race condition” is a hypothesis, not evidence. Another is adding a timeout and calling the incident fixed. That can turn a visible hang into a less visible partial write.

The safer habit is to say which layer owns the failure. In this example, the service owns the promise it exposes to its caller, so it needs a defined outcome. The storage layer may need its own connection and cancellation controls. The caller may decide whether a retry is safe. Those responsibilities are related, but they are not the same patch.

This is also why a tiny reproduction is so useful in a repository interview. It proves you know where to draw a boundary before you start changing code.

How should you practice this without memorizing a speech?

Pick one bug-shaped prompt from a project you know: a stale cache, a duplicate webhook, a slow query, a failed upload, or a message that arrives twice. Write one sentence describing the contract. Then make one test that proves the bad behavior and one test that protects the good path.

Say the five steps out loud while the code is open. If the explanation falls apart, the problem is usually not speaking ability; it is that the boundary or the evidence is still vague.

For structured mock practice around this kind of explanation, aceround.app — AI interview assistant can be useful as a rehearsal surface. Keep the example grounded in work you actually did; the goal is a clear investigative process, not a polished fictional incident.

Disclosure: AI tools assisted with editorial review and the workflow illustration. The code example and its success and timeout behavior were manually checked with Node.js before publication.