Works locally, 404 on the server? Check filename case
Short answer: If images, stylesheets or pages work on your Mac or Windows laptop but return 404 on the live Linux server, check the capital letters. Linux treats Logo.png and logo.png as different files; macOS and Windows usually don't. The fix is to make references and filenames match exactly, rename files through Git with git mv so the change is actually recorded, and adopt a lowercase-only naming rule for web files.
Why it only breaks on the server
Most laptops use file systems that ignore case by default. Ask for images/Team-Photo.jpg and the system happily returns images/team-photo.jpg. Most Linux servers use case-sensitive file systems, where those are two different names. So a reference that works perfectly during development quietly breaks after deploy.
Git's own documentation acknowledges this difference. Its core.ignoreCase setting exists to make Git work better on file systems that aren't case sensitive, such as APFS, HFS+, FAT and NTFS. The documentation gives an example: if a directory listing finds "makefile" when Git expects "Makefile", Git assumes it's the same file and keeps remembering it as "Makefile". Git also sets this automatically when a repository is created on such a file system.
That's helpful for everyday work, but it explains a classic trap: rename a file by changing only its case in your file manager, and Git may not register the rename at all. Your laptop shows the new name, the repository still holds the old one, and the server gets the old one.
Common symptoms
- Images or icons missing on the live site but fine locally.
- A stylesheet or script returning 404, so the page looks unstyled or a feature doesn't work.
- Imports failing in a build on CI with "module not found", while the same build works locally.
- Two files that differ only by case appearing in the repository, such as
README.mdandreadme.md, confusing anyone on a laptop. - Links in the CMS or content files pointing at
/About-Uswhile the page lives at/about-us.
Finding the mismatch
- Look at the exact failing URL in the browser's network panel or server logs, including capital letters.
- List the file as the server has it. On the server, or in the repository with
git ls-files | grep -i photo, check the exact stored name. - Search the code for the reference and compare letter by letter.
- Run your build in a case-sensitive environment, such as a Linux container or CI, so these errors appear before deploy.
Renaming a file properly
To change only the case of a filename and have Git record it, rename through Git. The git mv command moves or renames a file and updates the index in one step:
git mv Team-Photo.jpg team-photo.jpg
On some case-insensitive systems, a direct case-only rename may be refused or behave oddly. A reliable workaround is a two-step rename via a temporary name:
git mv Team-Photo.jpg temp-name.jpggit mv temp-name.jpg team-photo.jpg
Commit, push and check the server or CI output to confirm the new name arrived.
Avoid changing core.ignoreCase yourself to "fix" this. The setting describes the file system you're on; setting it wrongly can make Git misbehave.
Fixing references
After renaming, update every place that refers to the file: templates, CSS url() values, JavaScript imports, Markdown content, CMS fields and email templates. A project-wide case-insensitive search for the filename finds them quickly.
For URLs that have already been shared or indexed with the wrong case, add redirects from the old form to the correct one on the server, so visitors and search engines land in the right place.
Prevent it with naming rules
The simplest prevention is a convention everyone follows:
- Lowercase only for web-facing files and folders.
- Hyphens instead of spaces or underscores, such as
team-photo.jpg. - No two files that differ only by case, anywhere in the repository.
You can enforce this automatically:
- A lint rule or small script in CI that fails if any tracked web file contains capital letters.
- Import plugins for JavaScript linters that check import paths match the real file's case.
- A build step that runs on Linux, which catches mismatches as missing files.
Test environments should match production
Many case problems survive because nothing between the laptop and the live server is case-sensitive. If your staging server or preview deployments run on the same operating system as production, a broken reference shows up there first, where it costs nothing. Containers help here: developing inside a Linux container on a Mac or Windows laptop means the app sees a case-sensitive file system day to day, so mismatches surface while you're still writing the code.
CMS uploads and user-supplied files
Uploads through a CMS can introduce the same problem: an editor uploads Menu-Summer.PDF and later links it as menu-summer.pdf. Many CMSs normalise filenames on upload; if yours doesn't, configure it to lowercase names or replace them with generated ones, and always link through the CMS's own media picker rather than typing paths.
A worked example
Take a hypothetical Hobart café group whose new website showed missing photos on two location pages after launch, although everything had looked right on the designer's Mac. The server logs showed requests for Images/Salamanca-Interior.jpg, while the repository held images/salamanca-interior.jpg; the designer had renamed folders in Finder and Git had never recorded the case change for one of them. The developer renamed the folder through git mv via a temporary name, fixed the references, added a CI check rejecting uppercase web filenames, and set up redirects for the two broken URLs.
FAQ
Is this a Linux bug?
No. Case-sensitive file names are normal on Linux. The mismatch is between development and production environments.
Do URLs care about case?
The path part of a URL can be case-sensitive, depending on the server. The domain name is not.
Can I make my Linux server case-insensitive?
It's possible in some setups but rarely worth it. Fixing names and references is cleaner.
Will this affect Windows servers?
Windows servers generally ignore case, so the problem appears when moving between platforms in either direction.
If parts of your site break only after deploying, tell us what's going missing and we'll help track it down.