Are you struggling to understand why your project runs locally but errors out with missing files or logs that point toward issues with case when you try and build on Netlify? You are not alone. Here is a guide to understanding how case sensitivity issues present themselves, why they arise, and how you can fix them!
1. Errors you might see
Case sensitivity issues can be frustrating to debug because sometimes you’ll receive error messages letting you know that files could not be found when they are clearly present during the build process. See this post for a great example:
Sometimes you might just have a failing build without any useful error messaging. (it depends on which file has the issue.)
2. Why does this happen?
If you working on Windows or OSX (mac), so the majority of computer users, you are working on a case-insensitive system. The file system used in Netlify builds is case sensitive, while your local environment is not. Unfortunately, the error messages that result may not clearly indicate this!
Meaning: if your code includes a file or reference to a file like
jQuery/jquery.js — the Netlify build may fail due to the mixed case filename. This issue can be present with ANY file that is an important part of your project, including, but not limited to:
- entry-point application files like App.js or Main.js (not the same as app.js or main.js)
- Partials, modules, imports, templates
- Dependencies, packages
- Font files
- Image, css and json files
- Netlify.toml, _redirects, package.json, Gemfile or any other config or settings files
- Anything else basically.
This issue also happens regardless of where the case sensitivity occurs. To be really clear:
somefile.js != someFile.js != SomeFile.js != SOMEFILE.js != sOmEfIlE.js
during the Netlify build step.
We strongly recommend that you pay very close attention to how you use case from the very beginning in your project, and standardize how you use case throughout so you don’t have problems during the build step on Netlify.
3. How can I fix these problems?
If you haven’t committed your files to version control (we are assuming you are using Git) then it is sufficient to simply rename the file(s) in question and the problem should fix itself.
That said, most people realize they are having a case issue when they try and build on Netlify, as the problem doesn’t occur locally. This almost always means that the file(s) have been committed to Git and pushed to a provider such as GitHub. Simply renaming the file and re-committing and pushing it does not generally work because Git’s default setting is to ignore case, and so those changes aren’t always registered.
This thread on stackoverflow has lots of useful approaches on how to deal with this. We have also found that:
- deleting the file
- committing and pushing to GitHub
- re-creating the file
- adding, committing, pushing to GitHub
Also does the trick.
As soon as the case issue is resolved, you should see any problems related to this vanish and enjoy smooth, problem free builds on our platform
If you are still having issues after fixing the case related issues, this Common Issue contains many other troubleshooting steps for common concerns! Good luck, comment below if you have additional thoughts!