What to Do When a Freelancer Delivers Broken Code

What to Do When a Freelancer Delivers Broken Code

Broken code is not the same as a normal bug. A normal bug appears in a feature that mostly works; broken code can stop a release, block a login, or make the file unusable on day 1. That difference matters because your next move should match the damage, not your mood.

Start with one question: can anyone safely use it? If the answer is no, treat it as a delivery problem, not a polishing task. If the answer is yes, but one path fails, you are likely dealing with a defect that still needs correction. Simple, but useful.

What counts as “broken code” versus a normal bug?

Broken code usually shows up in 3 forms: incomplete work, unstable work, or work that cannot run in the agreed setup. A form button that throws an error on submit is a bug. A checkout flow that never reaches payment because the freelancer skipped validation, the routing file, or the required API hook is broken code.

Look at the scope first. If the freelancer promised a page builder and delivered only the header, that is not a small defect. If the freelancer delivered a script that depends on a file never mentioned anywhere, that is also not a small defect. The code may exist, yet the delivery is still broken.

One practical test helps: can the code be judged against the agreed outcome in under 5 minutes? If you need hidden knowledge, secret setup steps, or a private explanation to make it behave, the problem is bigger than a typo. This is the point where many clients should revisit their notes and, if needed, compare the issue with how to hire a freelancer safely for the next project.

What should you check first before contacting the freelancer?

Reproduce the issue once before you write. Twice is better. Use the same browser, the same device, and the same account if possible. Write down exactly what you clicked, what happened, and where the failure appeared. “It doesn’t work” is too thin to help anybody.

Then note the environment. Record the browser name, version, operating system, server URL, and whether you used staging or production. A code path that works in Chrome on a laptop may fail in Safari on a phone, and that difference can save a lot of back-and-forth later.

Collect the hard evidence while it is still fresh: screenshots, console messages, server logs, error IDs, and the timestamp of the failure. If the bug appears after a deploy, note the exact file or version you received. These details turn a vague complaint into a usable report.

Do not change three things at once. If you edit the config, replace the dataset, and restart the service, nobody can tell which change caused the failure. Keep one test path fixed.

How should you report broken code without turning it into an argument?

Keep the first message short, factual, and dated. A good structure is: 1) what failed, 2) where it failed, 3) what you expected, 4) what you need next. That is enough to open a repair conversation without sounding accusatory.

Example: “On the staging site, the contact form returns a 500 error after submit. I expected the form to send the message and show a confirmation. I attached the screenshot and the console log. Please confirm the cause and send a fix or a corrected build.”

That wording leaves no room for theater. It also avoids the trap of blaming the freelancer for intent, which you cannot prove anyway. Keep the sentence about the impact concrete: “customers cannot submit orders,” “the admin panel freezes,” or “the exported file is empty.” Those details matter more than emotions.

If the project touched public-facing work, the message should mention the consequence clearly. A broken landing page can waste a marketing budget in hours; a broken checkout can cost sales immediately. No one needs a dramatic paragraph to understand that.

What proof should you share so the freelancer can fix it faster?

Send the steps to reproduce in order, not as a story. Step 1: log in. Step 2: open the dashboard. Step 3: click Export. Step 4: the download fails. That kind of list lets the freelancer retrace your path exactly.

Include the test data that triggered the problem, such as a demo account, a sample record, or a specific file name. If the code depends on a language setting, a browser extension, or a specific environment variable, mention it. One missing detail can waste an afternoon.

Share version info for the deliverable itself. If you received “v3,” say so. If the freelancer pushed a patch after your last review, say which patch. If there is a private repository, include the branch name and the commit hash.

Files help, but only the right ones. A screenshot of a blank screen is useful. A 4-minute screen recording can be even better if it shows the clicks and the failure in one pass. This is where the phrase freelancer reviews sometimes becomes relevant, because a pattern of unclear handoffs often shows up there before it shows up in the code.

When should you ask for a fix, a rollback, or a refund?

Choose the remedy by severity, not by frustration. If the bug is minor and the codebase is otherwise usable, ask for a fix. If the broken code blocks a launch or corrupts data, a rollback may be the fastest safe move. If the deliverable is unusable or unsafe to repair, a refund becomes reasonable.

Ask one direct question: can this be fixed without damaging other parts of the project? If the answer is uncertain, and the freelancer is guessing, rolling back may protect you better than waiting. A bad patch can turn one broken module into three broken modules.

Refunds should not be the first threat in message 1. They belong after a clear review of the evidence and the delivery terms. Still, if the work cannot be repaired in place, or the freelancer admits the architecture is wrong, you should stop treating the file as if it were only one step away from finished.

There is a practical edge here. If a release is blocking revenue, every hour of delay has a cost, even if you do not calculate it to the cent. If the project is private and low risk, the fix can wait longer. Context matters.

What if the freelancer says the code works on their side?

Do not treat that answer as a fight. Treat it as a clue. In many cases, the issue is an environment mismatch: one machine has cached dependencies, another uses a different Node version, or one server hides a missing file behind a local setup step.

Ask for the exact setup the freelancer used. Request the version numbers, install steps, and any manual steps they followed after cloning or uploading. If they say “it worked locally,” you need the local recipe, not reassurance. That is the whole point.

Sometimes the code depends on a silent assumption. The freelancer may have assumed an admin account exists, or that a config file was already present, or that the database already contains a seed record. Those assumptions should have been documented, but now the immediate task is to expose them one by one.

Keep the tone calm, even if the answer feels evasive. A line like “Please send the exact setup steps you used so I can compare them with my environment” is enough. If the freelancer is cooperative, the gap often closes fast. If not, you at least know the problem is no longer technical alone.

When does broken code become a handoff or ownership problem?

Broken code becomes a handoff problem when the files arrive without the steps needed to run them. That includes missing installation notes, missing access details, missing environment files, and missing deployment instructions. The code may be present; ownership is not.

This happens often in projects that depend on a team, not one person. A developer sends a repository, but the server credentials live in a private message. A designer hands over a site theme, but the build tool is never named. A backend script runs only on the freelancer’s machine because the rest of the setup was never written down.

At that point, the problem is not only “fix this bug.” It is “can my team adopt this work at all?” If the answer is no, the delivery is incomplete, even if every file looks tidy. This is where the rules of the rules of the 24freelance.pro site. freelance can be a useful reference point for how work, files, and communication should be handled.

Some teams also need a transfer checklist before they accept the project. One line for access. One line for hosting. One line for admin credentials. One line for the folder structure. Without that, the handoff can fail even when the code itself is sound.

How do you prevent the same delivery problem next time?

Write acceptance criteria before the work starts. Not a paragraph. A list. “Login succeeds with valid credentials.” “Export produces a CSV with 3 columns.” “The form sends the email and shows a success message.” Those lines make broken code easier to spot because the target is visible.

Ask for test cases in advance, especially for features with 2 or more branches. If the freelancer knows how you will test, they are more likely to build for the real check, not for an imagined one. Staging review helps too, because it catches broken code before anyone calls it finished.

Define “done” with one sentence that includes files, access, and proof. For example: “Done means the code runs on our staging server, the README lists setup steps, and the test account verifies the main flow.” That definition will not solve bad work, but it will make the bad work visible sooner.

For complex tasks, ask for a short handoff note. Even 5 bullets can save you later: environment, dependencies, known limits, test data, and who owns the next step. Small request, large payoff.

One last practical habit: keep the project chat and the final file list in the same place. If the freelancer sends a fix by email, but the deployment note lives in chat and the server password sits in a spreadsheet, the handoff is fragile. Fragile handoffs fail under pressure.