Last week, I cloned the SearXNG GitHub repository to get it running locally, enabling me to add a search engine agent to my LM Studio configuration. I followed the installation instructions, but I encountered a litany of errors. I checked that Colima was running and opened up Orbstack, and per usual, I saw one of the containers bouncing. 🤦🏻

I’m sure the README.md worked on their machine.

After a couple of hours of debugging, I finally got it running. Yes, I used multiple LLMs, both in my IDE and on the web, to help me.

This is the mcp.json I used in Orbstack:

{
  "mcpServers": {
    "searxng": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-searxng-public"
      ],
      "env": {
        "SEARXNG_BASE_URL": "http://localhost:8888"
      }
    }
  }
}

It’s cool once it works.

SearXNG running in Orbstack

The wayward developer knows not what they do, but they wear the t-shirt revealing who they are and the path of destruction they’ve left behind.

¯\_(ツ)_/¯

“It works on my machine.”

— The Wayward Developer

I love Open Source and InnerSource software. I hate spending time in debugging vortexes because someone failed to test, document limitations, or created a complex jungle that requires a digital machete to cut through it. 🔪

The wayward developer’s heart is in the right place; they want to share their creation. But the git clone wars begin between them and untold developers when it only works on their machine.

Everyone Knows This Pain

Every developer has been here. You find a promising library or tool, clone it, run the setup commands, and nothing works. The error messages are cryptic. The documentation is outdated. The examples don’t run. You’re stuck in missing-dependency hell, trying to figure out why this tool refuses to run.

I’ve seen Docker containers fail due to zero-pin architectures. I’ve debugged Python packages that worked once and never worked again. I’ve heard stories from teammates wasting an inordinate amount of time debugging someone’s “simple” tool, tested on one developer’s machine.

This isn’t about being ungrateful for generous software developers. I’m calling out the wayward developers who create software, test it once on their machine, and ship it without a care in the world. 💸

The worst part? You can’t even be livid at them because they’re trying to help. But honorable intentions don’t fix broken software or your headache.

Explosion Explosion Walk Away

Costs of Untested Software

Do the math. If 1,000 developers waste 2 hours each on inadequately tested software, that’s 2,000 hours lost. At $50/hour, the “free” software costs $100K in productivity. Whoops!

That’s the direct cost. Add in the frustration, the lost momentum, the “maybe I should build this myself” thoughts, the eventual abandonment of excellent tools, and lost contributors.

Stop Being Part of the Problem

Test Across Environments

GitHub Actions makes this easy.

Before you ship your software to an SCM server:

  • Test on multiple operating systems (Windows, macOS, Linux).
  • Test with different dependency versions (not just the latest).
  • Test in clean environments using Docker containers.
  • Automate all tests in CI/CD pipelines.
  • Document exact versions that work in your README.
  • Use dependency lock files (package-lock.json, Pipfile.lock, etc.).

Make It Easy for Others

  • Write clear setup instructions with copy-paste commands.
  • Include a troubleshooting section for common issues.
  • Provide working examples, not just documentation.
  • Test your examples before publishing.
  • Use semantic versioning properly.
  • Include a CONTRIBUTING.md file with setup instructions.

Pro tip: If your setup instructions are longer than your actual code, you’re doing it wrong. Automate away complexity.

Trust and Quality

Software that wastes everyone’s time isn’t free. It destroys trust and makes developers question whether open source is worth the frustration. Given the current state of commercial software enshitification and cost-hike trends, especially with Software as a Service, I don’t want to deter new developers from joining the enduring Open Source Software movement.

If a developer can’t test their software across different environments — or at least document where it works — they shouldn’t ship it. Period. Testing on one machine is lazy, unprofessional, and disrespectful.

Software ecosystems depend on trust. Every time a developer ships untested software, they break that trust. Stop being part of the problem. Fix it today by helping developers fix issues with their documentation and code.

Share this with your team. Forward it to the developer who ships broken Docker containers and tag the maintainer who hasn’t updated their README since 2019.

What’s your wildest “works on my machine” story? Drop it in the comments.

Want to see other deadly cuts?

References