Back to Cookbook
KiloClaw

Works Locally, Fails in CI Debugger

Diagnose the environment mismatch without trial-and-error pushes

When builds or tests pass locally but fail in CI, this recipe compares commands, environments, and dependency resolution to pinpoint the mismatch quickly.

CommunitySubmitted by CommunityWork10 min

INGREDIENTS

🐙GitHub

PROMPT

Create a skill called "Works Locally, Fails in CI Debugger". Given: - Local command(s) that pass - CI job logs and the exact CI command(s) - Versions (OS, runtime, package manager) Output: - A diff checklist (command, versions, lockfile, env vars) - The top 5 likely causes ranked by evidence - A minimal fix plan plus a prevention plan (pinning, smoke tests, env checks)

How It Works

CI runners start from clean images and differ from laptops. This recipe standardizes how

you capture differences and confirm the true cause.

Triggers

  • "npm/gradle/go test passes locally but fails on CI"
  • CI errors disappear when you change runner OS/version
  • Failures correlate with dependency install or build steps

Steps

  1. Verify that local and CI run the same command (no "file-only build" shortcuts).
  2. Compare versions: runtime, package manager, OS, shell, build tool.
  3. Confirm lockfile usage (CI should install from lockfile deterministically).
  4. Capture CI logs + artifacted lockfile + dependency tree.
  5. Reproduce CI locally via container runner (best-effort parity), then fix root cause.

Expected Outcome

  • The mismatch becomes explicit: command difference, version drift, missing dependency, or CI-only constraint.
  • Fixes stop being trial-and-error pushes.

Example Inputs

  • "GitHub Actions fails `npm run build`, local is fine."
  • "Gradle plugin resolves locally but not in CI."
  • "Tests pass local but fail on headless Ubuntu runner."

Tips

  • Treat CI as the source of truth for what "mergeable" means.
Tags:#build-failures#ci-cd#environment-setup#debugging