eas-build-doctor

Diagnose and fix Expo and EAS build failures using a casebook of real root causes.

Updated Aug 21, 2026
One-click install
npx skills add https://github.com/allen-hsu/mobile-shipkit --skill eas-build-doctor-allen-hsu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: eas-build-doctor
Source: https://github.com/allen-hsu/mobile-shipkit/tree/main/skills/eas-build-doctor
Command: npx skills add https://github.com/allen-hsu/mobile-shipkit --skill eas-build-doctor-allen-hsu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? EAS cloud and local builds fail with cryptic errors — swallowed messages, lockfile rejections, fingerprint mismatches, gradle crashes — and the official docs rarely cover the actual root cause. This Skill maps eleven real, field-verified failure cases from symptom to root cause to fix, so you stop guessing and start fixing. ## Core Features & Use Cases - Symptom-first casebook: Eleven documented failures (npm ci lockfile drift, .easignore archive bloat, expo-updates fingerprint mismatch, Swift compile errors, Metaspace OOM, gradle cache corruption, swallowed node errors, ExtraTranslation lint, ERESOLVE peer conflicts, Kotlin return-type errors), each with root cause and a repo-committed fix. - Diagnostic toolbox: Decompress brotli EAS logs, keep the local build working directory, replay gradle by hand, and inspect what went into the expo-updates fingerprint. - Environment vs repo triage: A simple rule — if local and cloud both fail, the problem is in the repo; if only one side fails, it is the environment. - Use Case: Your cloud build fails at Configure expo-updates while local works. The Skill points you to stray ios//android/ directories or hand-edited node_modules, and prescribes patch-package plus fingerprint comparison to fix it permanently. ## Quick Start Ask the agent to diagnose your EAS build failure by pasting the error message, for example: my eas build fails with npm error Invalid lock file, find the root cause and fix it.

Frequently Asked Questions about eas-build-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix EAS build failing with npm ci lockfile errors?▼

Regenerate the lockfile from scratch: delete node_modules and package-lock.json, run npm install, then verify with npm ci --dry-run in a clean directory. Incremental npm install leaves platform-specific residue that only fails on the Linux builder.

Why did my EAS build archive get bigger after adding .easignore?▼

Once .easignore exists it fully replaces .gitignore, so node_modules and .git get packed back in. The fix is to re-list everything .gitignore excluded inside .easignore, including node_modules/, .git/, /ios/, and /android/.

How do I fix expo-updates runtime version or fingerprint mismatch?▼

Remove any local ios/ or android/ directories, since CNG projects must never commit native folders, and route all node_modules edits through patch-package so local and builder installs are byte-identical. Compare fingerprints with npx expo-updates fingerprint:generate.

Can I run EAS builds locally when cloud quota is exhausted?▼

Yes, run eas build --local --platform ios or android with your production profile. It uses the same pipeline and credentials pulled from EAS, and the resulting .ipa or .aab can go straight to eas submit, asc, or gpc.

Why does my Android build fail with only 'node exited 1' and no stack trace?▼

A hook appended to gradle.properties without a leading newline fused a value onto the previous line, breaking an autolinking argument. Rerun with ./gradlew --info to see the full node command line, and append with printf '\n...' instead of echo.

How do I read the full EAS cloud build log?▼

EAS log downloads are brotli-compressed, so decompress with brotli -d build.log.br or a one-line Python brotli script. The web summary omits the details needed to find root causes.