Claude Code Not Working? What to Check First

When Claude Code is not working on a real project, the safest first step is not another broad prompt. The symptom may be a failed build, an app that will not start, TypeScript errors, a blank screen, broken routes or a generated feature that looks finished but does not actually work. Those symptoms can come from different layers of the project.

The useful question is: what changed, and where is the project actually failing? If you need practical repair rather than more trial and error, start with Claude Code repair.

What the problem usually looks like

A Claude Code project can appear broken in several ways. The dev server may refuse to start. The build may fail after dependencies were changed. A React screen may render blank. A route may return a 404. TypeScript may report errors across files Claude Code touched and files it did not mention. Sometimes Claude says the task is complete, but the browser, compiler or deployment logs say otherwise.

That mismatch is common with AI-assisted code work. Claude Code can be helpful, but it does not replace testing, version control, build checks and technical review.

Likely causes

The cause may be generated code that does not match the existing architecture, imports that point to the wrong files, dependency versions that do not fit, a configuration change, an environment variable problem, a routing mismatch, or a component that now receives different props from the ones it expects. In a Next.js or React project, one small generated assumption can break a wider flow.

If the error is unclear, use root cause diagnosis before accepting more edits.

What to check first

Check the earliest meaningful error, not the last one printed in the terminal. Run the project, read the first build or TypeScript failure, open the browser console, and compare changed files with the last known working state. If you use Git, check the diff before asking Claude Code to fix anything else. If you do not use Git, list the files Claude touched and preserve a copy before continuing.

Also check whether the problem is local only, build-only or deployment-only. A project that runs locally but fails to build needs different repair from one that cannot install dependencies.

What not to do

Do not ask for a full rewrite unless you are prepared to lose working behaviour. Do not paste a vague prompt such as “fix the app” after several failed attempts. Do not accept changes to unrelated files without reviewing them. Do not hide TypeScript errors by loosening types unless you understand the risk. Do not remove dependencies just because one error mentioned them.

For generated code faults, AI code repair is usually safer than piling on another broad prompt.

When to stop prompting and get help

Stop when Claude Code keeps changing the same area without stabilising the project, when each fix creates another error, when working features start breaking, or when the project is needed for a client, launch or live business workflow. If the site or app is already affecting customers, emergency website fixes may be more appropriate.

Practical checklist

• Record the exact command, route or user action that fails.
• Read the first meaningful terminal, TypeScript or build error.
• Open the browser console and network panel if the app loads but behaves badly.
• Review changed files before accepting more AI edits.
• Check imports, dependencies, routes, props and environment variables.
• Protect the last known working version if one exists.
• Ask for a small targeted fix only after you know the failing layer.

How to make the next repair safer

Once you know the failing layer, narrow the next change. A good repair prompt should name the exact command that fails, the first error, the files that changed recently and the behaviour that must be preserved. Ask for a small patch, not a redesign. If Claude Code proposes changes across many unrelated files, stop and review why those files are involved.

It also helps to separate code faults from setup faults. If the app cannot install dependencies, component edits will not help. If the build passes but the browser shows a runtime error, the console and data flow matter more than package changes. If deployment fails, compare local build output with production logs before changing app logic.

What a proper repair should achieve

A proper repair should leave the project easier to understand than before. The app should run, the original failing journey should be tested, and the change should be explainable in plain English. If a workaround hides the error but leaves fragile code behind, the project may fail again when the next feature is added.

For business or client projects, also check whether the repair affects mobile layout, forms, integrations, auth, API calls or deployment settings. The immediate error is only one part of project stability.

Conclusion

Claude Code not working does not mean the whole project has failed. It usually means the project needs a careful diagnosis before repair. Find the failing layer first, then make the smallest change that restores stability.