Drift tells you why your program works in one place and fails in another.
Give it the machine where the program fails and the machine where it works, a CI log, or an error message. Drift compares what differs, names the cause when the data supports one, and says what to try next. The essay explains why it exists.
curl -fsSL https://raw.githubusercontent.com/gmitch215/Drift/master/install.sh | shIt installs to ~/.local/bin; open a new terminal if drift is not found afterwards. It downloads the 1.0.0 release archive and checks its SHA-256. The script is install.sh if you want to read it first. Add | sh -s -- --from-source --ref BRANCH to the command to build a branch, tag or commit instead; that needs git, a JDK 17 or newer and several minutes. From a clone with JDK 21 you can also run ./gradlew :cli:jvmRun --args='why --error "TEXT"'.
Pick the case you have:
- A bug report someone sent you, with no access to their machine:
drift why issue.md. - A failed CI run:
drift whyinside the project's git checkout (needs the GitHub CLIghor the GitLab CLIglab, logged in). - Two machines you can reach: see Compare Two Machines.
- Only an error message: start below.
- Nothing broken right now:
drift demoreplays one recorded failure throughdrift why, offline.
Start with the error. The outputs below are copied from real runs. On the machine where the program fails, paste the line that says what failed:
drift why --error "Fatal error: Uncaught Error: Call to undefined function str_contains()"drift why: reading the error text
I found no environment fact in this error text (no tool version, operating system or setting), so I
cannot say what it points at.
What to try next:
To tell, run php -v where it fails and paste the result: the error text is PHP's, but the report
does not say which version runs it.
In one step: php -v | drift why --reply
No CI run or second machine was available, so I read only the error text. To compare with another
machine, add --there PLACE.
Drift does not stop at "I don't know". It names one check, and you pipe the result back to continue the same session. Run the check where the program fails, then where it works:
php -v | drift why --reply
php -v | drift why --reply --works--reply continues the session that drift why saved in .drift/why/session.json in the folder where you started, so run it from that folder. If you run the second command on another machine, Drift prints one line to copy back to the first. It stores what it read from your answers, not the text you piped in. Once both sides are known, Drift compares them:
drift why: comparing the answers from where it works and where it fails
It most likely fails where it fails because PHP is 7.4.33 where it fails and 8.3.12 where it works;
it is the only difference I found.
What I found:
PHP version: 8.3.12 where it works, 7.4.33 where it fails
What to try next:
Use PHP 8.3.12 where it fails. Pin the version so the two stay equal, for example in
.tool-versions or your CI image. If there is no version manager where it fails, change the image
or package that provides PHP.
To be sure, change only that and run it again where it fails.
The answer has three parts: the verdict, what Drift found, and what to try next.
Use this when a program passes on your laptop and fails on a server. Install Drift on both. On the failing machine, save what Drift can read, with secret values hidden:
drift why --save there.jsonCopy the file to the machine where the program works and pass the error message the program printed:
drift why --there there.json --error "TypeError: Object.groupBy is not a function"drift why: this machine against the saved capture in there.json
Assuming it works here and fails there: it most likely fails there because Node is 20.20.2 there and
22.23.3 here; the error text points at it.
What I found:
your error text points at this: is not a function
Node version: 22.23.3 here, 20.20.2 there
What to try next:
Use Node 22.23.3 there. Pin the version so the two stay equal, for example in .tool-versions or
your CI image. If there is no version manager there, change the image or package that provides
Node.
To be sure, change only that and run it again there.
In Drift's answer, "here" is the machine where you ran the command, which is the one where the program works, and "there" is the saved capture of the machine where it fails. Without --error, Drift lists every difference that fits and names the one change that tells them apart.
drift why --error "TEXT" # only the error message; Drift asks for what it needs
drift why # latest failed CI run of this git checkout (needs gh or glab)
drift why --there docker:NAME # a running container, read only (needs Docker)
drift why --there user@host # another machine over ssh, read only (needs ssh access)
drift why -- make test # runs here; a later failure is explained against the last pass
drift why issue.md # an issue or error report (no machine access)Drift Studio does the same in an app: its Why screen takes a pasted error, bug report or CI log and asks you for the same checks. ./gradlew :studio:run opens it on the desktop, and the web build is at drift.gmitch215.dev/atlas, where Try a Sample loads a recorded failing CI run with nothing to install. Studio also builds for Android with ./gradlew -Pdrift.mobile=true :androidApp:assembleDebug and for the iOS simulator through iosApp/iosApp.xcodeproj. The CLI installs on Linux (x64 and arm64), macOS (Apple silicon) and Windows (x64). Install has the steps and prerequisites for every target.
When the report lacks the facts, Drift asks for one check at a time. When several differences fit, the answer lists them and says the data cannot separate them: change one on the failing machine to match the working machine and run the program again. When the report reads like a fault in the program, Drift may say it does not look like an environment difference. Treat that as a hint to check the code first. On 141 real issue reports it made 24 such calls: 8 matched a code fault or user error the maintainers named, 2 were environment problems, and 14 were threads where the maintainers named no cause.
Tool versions (Node, Python, PHP, Git, npm and others), environment variables with secret values hidden, resource limits, time zone, locale, the operating system release, and package versions locked in the project folder. A tool that is missing on the failing machine is reported as "not installed there". In a project folder, Drift also reads your source files to note the module names they import and a few fixed call patterns, such as a function that older PHP lacks. It keeps those names and a few short values, such as a script engine or keystore type, and not the source text, so a saved capture lists what your code imports. It skips this step on Windows. Drift does not read your data files or your network traffic. None of this needs Docker.
- Why: every flow of
drift why, with real output. - Install: downloads, package managers and building from source.
- Try It: commands to run against the recorded fixtures.
- Kotlin Portability Atlas: what 38 small programs print on each target.
- Architecture and Limits.
- ADVANCED_USAGE.md: every command and flag.
- TECHNICAL_REPORT.md: design, evidence and numbers.
- License: MIT.
Drift is written in Kotlin Multiplatform, so most of its code is shared across targets. See Shared Code.