1.2.1.5 Works On My Machine Failure

"Works on my machine" failure describes the situation where an application runs correctly on the machine of the person who built or tested it, but fails when run by someone else or in a different environment, revealing that the application's apparent correctness depended on undocumented characteristics of that one machine rather than on the application itself.

Why This Failure Is Hard to Diagnose

The phrase is often used with a degree of frustration because the failure report comes with no obvious explanation: the code has not changed, the steps to run it have not changed, and yet the result differs. The actual cause is almost always an environmental detail that was never made explicit — an installed library, a configuration file left over from another project, an environment variable set long ago and forgotten.

A Typical Example

A developer might have a global installation of a particular tool version that their project silently relies on, without that dependency being declared anywhere in the project itself. Anyone else attempting to run the project gets a different, often older or newer, version of that tool and the application behaves differently or fails outright.

which python3
python3 --version

Run on the original developer's machine versus a colleague's machine, these commands frequently reveal the actual discrepancy behind a "works on my machine" report.

How Docker Eliminates the Undocumented Dependency

Docker forces every dependency the application relies on to be explicitly declared in the Dockerfile, because nothing exists inside the container unless it was put there deliberately. There is no possibility of a silent, undeclared dependency on something that merely happened to already be installed on one particular machine.

FROM python:3.12-slim
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

docker build -t myapp .
docker run myapp

If this image runs correctly on the original developer's machine, it will run identically anywhere else Docker is installed, because nothing about the original machine's particular history or configuration can leak into the container.

Proving the Failure Is Gone

The most direct way to confirm a "works on my machine" issue has actually been resolved is to run the containerized application on a machine that has never had any version of the project's dependencies installed before, and confirm it behaves the same way.

docker run --rm myapp python -m pytest

The Broader Lesson

This kind of failure highlights that "the application" is never just the source code — it is the source code plus everything the code implicitly assumes is already present in its environment. Containerizing an application makes those assumptions explicit and enforces them everywhere it runs.