Hackathon Demo Fails on Clean Checkout: What Your Machine Had

If your hackathon project works on your laptop but fails immediately after a fresh git clone on a judge’s machine, the cause is almost always a dependency or configuration that exists only in your local environment — not in the code. This article explains the most common culprits, how to diagnose them quickly, and how to prevent the failure before you submit.

Why “It Works on My Machine� Happens

During a hackathon, you’re under time pressure. You install packages, tweak configuration files, set environment variables, and maybe run a database that you started months ago. None of that is captured in your repository unless you explicitly save it. A clean checkout gives you only what’s in version control — no hidden state, no global tools, no background services.

The most common failure points are:

• Missing dependencies — the requirements.txt, package.json, or Gemfile is incomplete or not committed.
• Environment variables — API keys, database URLs, or secret tokens are stored in a local .env file that isn’t in the repo.
• System-level tools — you used a library that needs a native binary (like libpq for PostgreSQL) that isn’t installed on the judge’s machine.
• Hardcoded absolute paths — your code references /Users/yourname/project/data.csv instead of a relative path.
• Uncommitted files — you added a file but forgot git add, so it’s not in the commit.

How to Diagnose a Clean Checkout Failure

When the demo fails, don’t panic. Work through this checklist in order:

1. Read the error message — it usually tells you exactly what’s missing (e.g., ModuleNotFoundError: No module named 'flask').
2. Check if the dependency is declared — look at your requirements.txt or package.json. If the missing module isn’t listed, that’s your answer.
3. Verify environment variables — if the error mentions a connection to a database or an API, check if you’re using os.environ['DB_URL'] without a fallback.
4. Look for hardcoded paths — search your code for absolute paths like C:\Users\ or /home/.
5. Test with a fresh clone yourself — before the demo, clone your repo into a new directory and run it. If it fails there, you’ve found the problem.

Common Culprits: Dependencies and Lock Files

The most frequent cause is an incomplete or missing dependency list. In Python, you might have used pip install flask but never saved it to requirements.txt. In Node.js, you might have installed a package with npm install but didn’t commit package-lock.json, which pins exact versions.

Even if you have a lock file, the judge’s machine may have a different operating system or Python version. For example, a package that works on macOS might not have a pre-built wheel for Windows, causing a compilation error. Always specify the Python version in a runtime.txt or .python-version file.

Environment Variables and Secrets

Many hackathon projects use a .env file to store API keys, database credentials, or configuration flags. If you don’t commit that file (and you shouldn’t, for security), the clean checkout won’t have those variables. The code then crashes with a KeyError or a connection refusal.

To fix this, provide a .env.example file with dummy values and clear instructions on what to set. In your code, use a library like python-dotenv to load the file, and always provide sensible defaults for non-critical settings.

System Dependencies and Native Libraries

Some Python packages (like psycopg2 for PostgreSQL) require a C library to be installed on the system. If you installed it via apt-get or brew, that’s not part of your repo. The judge’s machine won’t have it, and the import will fail with a cryptic error like libpq.so.5: cannot open shared object file.

Solutions include using a pure-Python alternative (e.g., psycopg2-binary), or containerizing your app with Docker. Docker ensures that the environment is identical everywhere, but it adds complexity and may not be allowed in all hackathons.

How to Prevent It Before the Demo

Prevention is better than a last-minute scramble. Follow these practices from the start:

• Use a virtual environment (Python) or npm init (Node) and commit the lock file.
• Keep all configuration in environment variables, and commit a template file.
• Use relative paths in your code, or compute paths from __file__.
• Run your app on a fresh clone at least once before submission.
• If you use a database, either include a migration script or use an in-memory/SQLite fallback for the demo.

Frequently Asked Questions

Why does it work on my machine but not on the judge’s?

Because your machine has packages, environment variables, or system libraries that aren’t in your repository. A clean checkout only has the files you committed, so anything else is missing.

What should I do if I forgot to commit a file?

If you still have time, add the file and commit it. If not, you can copy the file manually to the judge’s machine, but that’s risky and often against the rules. Always check git status before submitting.

Is it okay to hardcode API keys in the code?

No. It’s a security risk, and it also causes failures on other machines. Use environment variables and provide a dummy example.

How do I make my project truly portable?

Use a container (Docker) or a virtual machine. That captures the entire environment, including system dependencies. If that’s not possible, document every dependency and provide setup scripts.

What if the judge’s machine has a different operating system?

That’s a common issue. Test your code on all major OSes if you can, or use cross-platform libraries. For native dependencies, prefer packages with pre-built binaries for all platforms.

Can I avoid this by using an online IDE?

Using an online IDE (like Gitpod or Replit) can help because it starts from a clean environment each time. But you still need to commit all dependencies and configuration.

Related

• Can AI Get Better Without Getting Bigger? Test-Time Compute
• Calculate Months Between Two Dates in Excel
• 7 Days to Die Same Key Already Exists Error Fix

in t | Finish time | min | 50 | 0
in d | Distance | km | 10 | 0
out pace | Average pace | min/km | t / d | 2
out speed | Average speed | km/h | d / (t / 60) | 2