The Five Common Issues and Their Fixes

Bookmark this one. The difference between a frustrating hour and a thirty-second fix comes down to knowing what to look for before it happens.

Files landing in the wrong place

The honest test first, with no path or folder named:

Create a new stylesheet for the projects section styling.

On a capable model, Claude usually reads your project structure and files it correctly anyway. That is the real lesson here. A clean folder structure is a signal every future prompt benefits from. When the project is organised, Claude files new things where they belong. When it is a pile of files in one folder, there is nothing to read your intent from.

On the smaller, faster models, a new file can still land somewhere odd. When the location genuinely matters, name it and remove the guesswork:

I need styling for the projects section. Put it in a new file at styles/projects.css, with the rest of the styles.

And if a file has already landed somewhere odd:

That styles.css ended up in the project root. Move it into the styles folder where it belongs, and fix anything that points at it.

It works on your machine and breaks on the live URL

Usually a capital letter in a file name, because your computer treats Hero.png and hero.png as the same file and the server does not. Or a change you saved but never committed and pushed.

My site works when I open it locally, but on the live URL the [describe what is broken, like a missing image or an unstyled section] is broken. Nothing looks wrong in my files. What could be different between my machine and the live site?

Claude knows to look for the things that differ between the two, and walks you through the fix.

CSS changes that refuse to show up

Almost always the browser cache. Your browser remembers the old file and serves the saved copy instead of downloading the updated one.

The quick fix is a hard refresh. Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows and Linux. That forces the browser to skip the cache and load the fresh files.

For a permanent fix during development, so you never think about it again:

I keep having to hard-refresh to see my CSS changes. Can you set the site up so the browser always loads the latest styles and scripts, and I never have to think about the cache while I am working?

Git never getting set up

You ask Claude to commit or push and it fails with fatal: not a git repository.

The prevention, folded into your very first prompt on any new project:

Before we start building, set up git with a sensible .gitignore and make a first commit.

The fix, if you forgot and you are already deep in:

We never set up git on this project. Set it up now, with a sensible .gitignore, and commit everything as it stands.

No progress is lost. Git starts tracking from that point forward.

The deployment failing with a build error

A build is a preparation step some sites need before going live. Your portfolio needs none, because the HTML, CSS and JavaScript you wrote are already the final files. So the error usually means Vercel assumed otherwise, went looking for instructions, and found none.

Copy the error from the deployment log, the screen Vercel shows when a deploy goes red, and paste it in:

My Vercel deployment failed with this error: [paste the deployment log error here]

The pattern across all five

Most problems come from one of two root causes. The prompt was not specific enough about paths, versions or configuration. Or a setup step got skipped early in the project.

Three habits prevent most of them.

1. Name specific file paths in your prompts.
2. Initialize git at the start of every project.
3. Be explicit about your deployment configuration up front.

These are project setup patterns that apply to any development tool. The advantage with Claude Code is that when one does happen, you describe the issue in plain English and Claude fixes it in seconds.

This resource is part of

Claude Code: From Beginner to Pro Agentic AI Engineer

by Arun Nagarathanam

Take your skills to the next level with

AI GEO 2026: Get Recommended by ChatGPT, Google, Perplexity

by Arun Nagarathanam