The first command overwrote two files I already had. My .gitignore lost the line that ignored .env , the file holding my API token, and my LICENSE came back as “Copyright © 2026 Voxgig”.

When I went looking for the cause, I found a .jostraca/ folder in my repo with 844 files inside it. The SDK generator writes its files through Jostraca, a code generator by Richard Rodger, who also wrote the SDK generator. So I spent an evening testing Jostraca 0.40.0 on its own, to find out whether the overwrite was Jostraca’s fault or a choice made on top of it.

The pitch

Jostraca’s docs open with a claim I agree with: the first run of a code generator is easy, and the hard one is the second run, after people have edited the output. Its answer is to split generation into two phases. Your callback builds a tree of components in memory, and only after that does a build phase write files, comparing each one with what’s already on disk.

import { Jostraca, Project, File, Content } from 'jostraca'

const jostraca = Jostraca({ existing: { txt: { write: true, merge: true } } })

await jostraca.generate({ folder: './out' }, () => {
  Project({}, () => File({ name: 'config.sh' }, () => Content('PORT=8080\n')))
})

There is no template language. Loops are for, conditions are if, and the only substitution syntax is $$path$$, which reads one value from the model and can do nothing else. I like this a lot, and so will anyone who has debugged a Handlebars partial late at night.

For files that already exist, you pick a mode per file type: write, preserve, present, diff or merge. The default is write, which overwrites.

That answered my first question. The SDK generator’s scaffolder passes existing: {txt: {write: true, merge: false}} explicitly, and sdkgen itself does the same. Jostraca overwrote my .gitignore because it was told to. The feature its homepage leads with is switched off in the tool that brought me to Jostraca in the first place.

Merge, when it works

I wanted to know whether merge deserved to be switched on, so I tested the case the homepage example avoids: the user and the generator both change the same line.

await run('PORT=8080\nHOST=localhost\n')
writeFileSync('./out/config.sh', 'PORT=3000\nHOST=localhost\n')  // my edit
const res = await run('PORT=9090\nHOST=localhost\n')              // generator change
console.log(res.files.conflicted)  // [ 'out/config.sh' ]

Jostraca doesn’t guess here, and if you run the generator again without resolving the conflict, the file is still listed in conflicted. My complaint is about what happens around it: generate() resolves normally and the process exits 0, while config.sh is now a shell script that won’t run. A CI job stays green unless you check res.files.conflicted yourself. The docs do tell you to check it, but I’d rather the safe behaviour were the default, with an option to opt out.

Merge, after git clone

A three-way merge needs a base. Jostraca keeps a copy of the previous output in .jostraca/generated/ , and it writes a .gitignore that keeps that copy out of git. So I played the part of a teammate: generate, add a line by hand, commit, then delete .jostraca the way a fresh clone would see it, and regenerate with merge on.

await run('PORT=8080\nHOST=localhost\n')
appendFileSync('./out/config.sh', 'DEBUG=1\n')   // committed hand edit
rmSync('./out/.jostraca', { recursive: true })   // what a fresh clone has
const res = await run('PORT=9090\nHOST=localhost\n')
console.log(res.files.written)  // [ 'out/config.sh' ]

DEBUG=1 is gone. There’s no conflict and no warning, and the file is reported as written, exactly like a normal overwrite.

The reference docs do describe this, in a section called “Merge needs a baseline, and degrades silently without one”. The explanation page says something else: that a colleague without the base gets a first merge that “degrades to a two-way comparison”. My test agrees with the reference. The README says every code sample in the docs is run by the test suite, and that’s true, but this sentence is prose, so nothing checks it. And the explanation page is where you’d go to decide whether merge is safe for a team.

Jostraca’s fix is control.version:true, which commits the base. For my Supabase SDK that’s 9.3 MB across 844 files, a second copy of the repo inside the repo. Copier, the Python project templater, handles the same problem differently. It commits a small answers file that records the template version, and on update it regenerates the old output in a temporary directory to use as the base. Jostraca generators are arbitrary code, so copying that approach is harder. But Jostraca already knows when the base file is missing, because that’s the check that triggers the fallback. It could warn, or refuse to merge. Today it falls back to the most destructive mode and says nothing.

Two substring matches

Two other features rely on plain string matching, and both caught me out.

Any file on disk that contains the text JOSTRACA_PROTECT, anywhere, is never overwritten again. I wrote a generator that emits a CONTRIBUTING.md explaining this feature to users. On the second run the generator couldn’t update its own file. It stayed at version 1, and every list in res.files was empty, so nothing told me the file had been skipped. The docs say to “emit the marker yourself only in files you intend people to adopt”, but a file that only mentions the feature counts as adopting it. Requiring a specific form, such as a line starting with JOSTRACA_PROTECT:, would prevent this kind of accident.

The replace option on templates has the same problem. A plain key matches anywhere, including inside other identifiers:

That output type-checks, runs, and reads two environment variables nobody sets, so the service loads undefined.json. You can write /\\bNAME\\b/ as a regex key instead, and the docs explain the matching rules clearly. Still, the short form is the one people will copy, and it’s the one that does the risky thing.

What I’d keep

Jostraca’s docs are more candid than most commercial products’ docs. They list their own sharp edges, like present doing nothing unless write is false, and they spell out what each design choice costs. Because the samples are tested, I could copy them and get exactly the documented output. The define-then-build split is a good idea, and I’d keep the no-template-language rule in any generator I wrote.

My problem is that most of Jostraca’s value depends on merge, and merge only works on the machine that ran the previous generation. Its biggest user has turned merge off, and the docs disagree with each other about what happens without a base. Until a missing base produces at least a warning, I’d use Jostraca the way sdkgen does: write mode, everything committed, and git diff as the merge tool. That works. But it leaves the component API and the missing template language as the reasons to pick Jostraca over a few hundred lines of my own fs.writeFileSync, and those aren’t what the homepage is selling.

You can find the codebase on GitHub; lassiecoder/jostraca-experiments

I tried to break Jostraca’s merge, and it survived until I cloned the repo was originally published in Tech Scoop on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you build React Native apps, you know this moment. You run the Android build, wait a few minutes, and the terminal ends with BUILD FAILED. Above it are hundreds of lines of Gradle tasks, deprecation warnings and “Run with — stacktrace” hints. The actual problem is in there somewhere.

iOS is no better. Xcode prints thousands of lines, CocoaPods has its own error format, Metro has another, and when the app builds but crashes on a device, the clue is buried in an adb logcat stream full of system noise.

I’ve lost more hours to finding the right line than to fixing the actual problem. So I built a tool for it: RN Build Doctor, a free, open-source command-line tool that reads React Native and Expo build, device and crash logs and tells you what actually failed, shows the evidence, and suggests what to do next.

npx rn-build-doctor

The problem: the last line of the log is rarely the real error

Here is the bottom of a real failed Android build from a React Native 0.87 app. This is what you see when the build stops:

The cause is in that log, but it’s surrounded by noise. And this is an easy one. In a release build with a JS bundling step, a native module and a Kotlin compile step, the real error can be several hundred lines above the end, and every toolchain formats errors differently.

The usual way to deal with this is to scroll, search for “error”, copy something that looks important into Google or an AI chat, and hope. That last option has a hidden cost too: build logs often contain file paths, tokens and environment values you probably shouldn’t be pasting into a chat window.

What RN Build Doctor does

You give it a log, either as a file or piped straight from the build:

(cd android && ./gradlew assembleDebug) 2>&1 | npx rn-build-doctor analyze -

For that same build, it prints:

Every finding has the same four parts:

1. What failed: the primary error, in plain words, not the last line of the log.

2. The evidence: the exact log lines (with their original line numbers) and the project files and versions involved.

3. What to do next: specific steps, not “try cleaning the build”.

4. How to verify: a command or check that tells you the fix worked.

It covers the places React Native builds break:

- Android / Gradle: JDK vs Android Gradle Plugin mismatches, Gradle too old, dependency resolution, AAR metadata and compileSdk requirements, duplicate classes, manifest merger failures (including a library that needs a higher minSdk), Kotlin and Java compile errors, and JVM options the JDK rejects.

- iOS / Xcode: code signing, CocoaPods version problems and missing specs, compile errors, linker errors, and the “Bundle React Native code and images” phase.

- Metro: unresolved modules (missing package, path alias, Node built-in, wrong relative path) and syntax errors.

- Runtime: JavaScript exceptions, red screens when a debug app can’t reach Metro, Android fatal exceptions, and iOS crash reports.

- Expo: app config, config plugins, SDK version mismatches, and environment variables that never reach EAS builds.

There’s also a project check (npx rn-build-doctor scan) that looks at your setup before you build: JDK version, Android SDK location, lockfiles, Expo config and env variables.

Three rules I built it around

1. Never guess

This was the most important decision. Each of the 40 checks has a specific trigger, required evidence, and the versions it applies to. If a failure doesn’t match any check, the tool doesn’t invent a cause. It says “No supported diagnosis” and shows you the first real error lines instead.

Every finding also carries a confidence level (high, medium or low) and lists what it can’t know. For example, a local scan can’t see variables stored in EAS, so it says so.

2. Evidence first

A diagnosis without proof is just a guess with good formatting. The report format won’t accept an error or warning finding without evidence, so you can always check the tool’s reasoning against the log yourself.

3. Offline and private

scan and analyze run entirely on your machine and make no network requests. The test suite fails if they try. .env files are read for variable names only, never values, and every report is redacted (tokens, keys, passwords, your home directory) before it’s printed or saved.

There is an optional AI explanation (rn-build-doctor explain) for failures the rules don’t cover. It’s opt-in, shows you exactly what would be sent with, dry-run, and labels its suggestions as unverified, separate from the evidence-based findings.

How it works

Under the hood there are two steps.

First, parsers read the log structure for each toolchain: Gradle’s “What went wrong” sections and failing task paths, Xcode errors and failed build commands, CocoaPods [!] blocks, Metro resolver and Babel errors, and logcat lines (grouped by process ID, so system noise doesn’t end up in the evidence).

Then rules run against those parsed failures plus your project files: package.json, installed packages, the Gradle wrapper, Android Gradle Plugin version, minSdk, gradle.properties, Podfile, and app config. That combination is what lets it tell an uninstalled package apart from a Metro cache problem, or point to the exact line in gradle.properties that breaks the build.

It’s written in TypeScript, and reports are validated with Zod and exported as Markdown or JSON, so you can attach a clean, redacted report to a GitHub issue or a Slack thread.

What testing it on real apps taught me

Synthetic test logs only get you so far, so before writing this I ran the published package against real projects: two React Native CLI apps (React Native 0.86 and 0.87, Gradle 9, AGP 8.12 and 9.2), an Expo SDK 57 app, Xcode 26 builds, CocoaPods, and an Android 14 emulator. I broke them in realistic ways and piped the output into the tool, exactly as a user would.

It found real problems in my own tool, which is the point of testing:

- Piping a live build crashed. The very first published version read piped input in a way that failed while the build was still writing (an EAGAIN error). Static log files worked fine; real pipes didn’t. Fixed in the next release.

- Apple changed the linker’s wording. Since Xcode 15, a missing library is reported as ld: library ‘X’ not found instead of the old ld: library not found for -lX. My rule only knew the old wording and gave the wrong advice.

- The New Architecture changed how “Metro not running” looks. In a modern debug build, an app that can’t reach Metro no longer crashes. It shows a red screen and logs a warning, so the tool said “no failure detected”. That’s one of the most common problems people hit, so it got its own check:

- CocoaPods warnings looked like errors. Every fresh React Native pod install prints “[!] hermes-engine has added 1 script phase”, using the same [!] marker as real errors. The tool reported a successful install as a failure. Now it knows the difference.

- One crash showed up as three errors. A JavaScript error at startup causes follow-on errors (“App has not been registered”). They’re now grouped under the error that caused them.

There were older-project lessons too. One of my older work projects still had -XX:MaxPermSize in gradle.properties, a leftover from old React Native templates. On a modern JDK, Gradle can’t even start, and the error is easy to miss. The tool now names the exact line:

Every one of those real logs, anonymized, became a regression test. The benchmark now has 67 labeled cases, 18 of them from real builds, including “near misses” that must not trigger a rule.

To try it in any React Native or Expo project (Node.js 22.12 or later):

# Check the project and environment
npx rn-build-doctor scan

# Analyze a failing build
(cd android && ./gradlew assembleDebug) 2>&1 | npx rn-build-doctor analyze -

# Analyze a crash or red screen on Android
adb logcat -d | npx rn-build-doctor analyze -

# Export a redacted report to share
npx rn-build-doctor report --output build-report.md

It also works in CI: pipe your build into a log and run analyze when the step fails, and the report can go straight into the GitHub Actions job summary.

What’s next

It’s version 0.1, and the catalog is narrow on purpose. I’d rather have 40 checks that are right than 400 that guess. The most valuable thing anyone can send me is a real build failure it doesn’t recognize. An anonymized log in a GitHub issue is how the next checks get written.

GitHub: https://github.com/lassiecoder/rn-build-doctor

npm: https://www.npmjs.com/package/rn-build-doctor

If this saves you an hour of scrolling through Gradle output, a star on GitHub helps other developers find it.

And I’d love to hear: what’s the most painful React Native build error you’ve had to debug?

React Native build failed? Find the real Error in your logs was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.