Lesson 26 of 30

Debugging a Failing Pipeline

Q: Walk me through how you'd debug a pipeline step that's failing in CI but passes when you run the same command on your own machine.

A strong answer covers: Reads the log for the actual error rather than trusting the final exit-code line; Reproduces CI's exact conditions locally — same runtime version, a clean/frozen-lockfile install, matching environment variables — rather than an approximate re-run; Names at least two concrete 'works locally, fails in CI' causes (timezone, case-sensitive filesystem, env var differences, test parallelism/race conditions); Treats reproduction as the goal before attempting a fix, rather than pushing speculative changes and re-running CI to see what sticks.

The pipeline is red and the log is 400 lines of noise. Learn to find the one line that matters, then reproduce it on your own machine instead of guessing.

15 min read

Check your understanding

Every option explains itself — why the right one is right, and why each wrong one is wrong. Miss one and it comes back later on a spaced-repetition schedule.

No quiz for this one — it's a practical topic

This topic is about judgment and practical tradeoffs more than a single right answer — a mock interview is the better way to test yourself on it.

Be interviewed on this →

Stuck? Ask the AI tutor

Hints without spoilers, and a plain explanation of why a wrong answer was wrong — answered only from this lesson. Free account, no card.

Interview questions on Debugging a Failing Pipeline

What interviewers actually ask about this, and what a strong answer has to cover.

Walk me through how you'd debug a pipeline step that's failing in CI but passes when you run the same command on your own machine.

A strong answer covers

Reads the log for the actual error rather than trusting the final exit-code line
Reproduces CI's exact conditions locally — same runtime version, a clean/frozen-lockfile install, matching environment variables — rather than an approximate re-run
Names at least two concrete 'works locally, fails in CI' causes (timezone, case-sensitive filesystem, env var differences, test parallelism/race conditions)
Treats reproduction as the goal before attempting a fix, rather than pushing speculative changes and re-running CI to see what sticks

Likely follow-ups

You mentioned matching the Node version — what if the workflow doesn't pin one explicitly? How would you find out what version actually ran?
Say the failure only happens about 1 in 10 runs, never locally. Does your debugging approach change, and how?
CI runners are Linux; a lot of frontend devs are on macOS or Windows. What's one class of bug that difference alone can cause?

Practice these with the AI interviewer →

The plain-language idea

A failing pipeline isn't a mystery — it's a program that ran on someone else's machine and left a complete transcript. Debugging it is two skills: reading that transcript to find the actual error under the scaffolding noise, and then reproducing the exact conditions that produced it locally, so you're not guessing blind.

Most CI debugging time is wasted on step one — scrolling past install logs, cache-restore messages, and framework banners to find the real failure — and step two gets skipped entirely in favor of "let me just push again and see."

See it in a real thing: a red check on this repo's own pipeline

Say the Run lib/ test suite step in .github/workflows/ci.yml goes red. The log tail looks like:

--- lib/ai/translate.test.ts ---
--- lib/content/tracks.test.ts ---
AssertionError: expected '2026-09-09T00:00:00.000Z' to equal '2026-09-08T23:00:00.000Z'
    at Object.<anonymous> (lib/content/tracks.test.ts:41:10)
Error: Process completed with exit code 1.

That single AssertionError line is the whole story — everything above it is just prior tests passing. Now reproduce it, matching CI's conditions instead of your own:

# 1. Match the exact Node version the workflow pins (node-version: 24)
nvm use 24

# 2. Clean install, not your locally-drifted node_modules
rm -rf node_modules
pnpm install --frozen-lockfile

# 3. Run the exact command the failing step ran, with the same env
TZ=UTC pnpm exec tsx lib/content/tracks.test.ts

Locally the test passed because your machine's timezone rolled the date differently. ubuntu-latest runners default to UTC; a dev laptop set to IST or PST won't. That's a "works on my machine" bug with a name, not a shrug.

What people usually miss

Watch out

The real error is rarely the last line. A failed step often prints a generic "Process completed with exit code 1" as its final line — that's the shell reporting the failure, not describing it. Scroll up to the first error-shaped line instead.
"Works locally, fails in CI" has a short list of usual suspects. Node/pnpm version drift, a stale local node_modules that doesn't match the lockfile, timezone differences (UTC on the runner vs. your local zone), case-sensitive filesystems (Linux runners vs. a Mac or Windows dev machine that silently tolerates Import from './Button' when the file is button.tsx), and env vars set in your shell profile that CI never had.
Parallel test races often only show up under CI's concurrency. A runner may execute tests with more parallelism than your laptop, or less — either direction can expose two tests sharing state (a port, a temp file, a module-level variable) that happened not to collide at your machine's parallelism level.

The genealogy: you're navigating the pipeline's own shape

Reading a CI log well means already knowing the structure it's printed in — which job failed, which step inside that job, and that everything after the failing step simply didn't run. That ordered structure of jobs made of steps is exactly what a pipeline's anatomy lesson laid out; debugging is that same map, read backward from a red X.