My blog website is hosted on Netlify’s cloud service. A while ago, there was a strange bug that prevented the site from publishing updates. This bug only occurred on Netlify, not on my own Mac. The error message on Netlify looked like this:

What’s strange is that this error didn’t always occur—9 times out of 10 there would be an error, but 1 time it wouldn’t. I searched for the bug for a long time but couldn’t find it. Eventually, I had no choice but to post on Netlify’s forum.

About a day later, someone provided a link to a person-to-person connection—wait, I mean a “discussion thread link.” Anyway, they thought my error message was similar to the error message mentioned in this thread and suggested I try the suggestions in the thread, which was to modify the referenced library version, i.e., modify the package.json file.

I clicked the link and looked at the thread. I judged that my error was probably unrelated to the referenced library version. However, there was someone in the thread who fixed it by changing Layout.js to layout.js in their file. Although this method didn’t work for others in the thread, this method caught my interest, and I followed this clue.

Case sensitivity

I’ll skip the digging process. In the end, I solved the case. The reason was that both Mac and Windows are case-insensitive by default (file names don’t distinguish between uppercase and lowercase). For example, whether you save a file as seo or Seo, they’re considered the same. So on your own system, if your code imports a file called Seo but the actual file name is seo, it might not cause problems during the build phase. However, when you deploy to Netlify, it will cause problems.

When Netlify builds a website, it uses a Linux system. Linux or Unix systems, or platforms like GitHub that store source code, are case-sensitive by default (file names distinguish between uppercase and lowercase). That is, seo and Seo are considered different files. The same location can have both seo and Seo files that only differ in case, which wouldn’t happen in the Mac and Windows world.

So on Netlify, if your code says “I want to import the file Seo” but the file name is seo, it will error. However, the same code on your own Mac or Windows might work fine.

Why it’s hard to find and doesn’t happen often

This bug, once explained, is actually quite obvious. Shouldn’t it be easy to find? But as shown in the error message at the beginning of the article, it’s not very obvious that this is the problem. It’s hard to find through Google, and weirdly, sometimes it doesn’t even show an error.

Another reason it’s hard to find is that the problem and solution aren’t in Netlify, but in Git and GitHub. Because the code and file names on GitHub are inconsistent, and Netlify syncs code from GitHub, that’s why Netlify errors occur.

Although Git is case-insensitive by default, in general cases, the situation I described above—where code and file names don’t match when deployed to Netlify—doesn’t happen often. If you initially save a file as Seo, the file name on GitHub and Netlify will also be Seo. That is, for files created for the first time, all systems can correctly distinguish case.

However, there’s a special case where errors occur: when you already have a file called seo on your local machine, and it’s already uploaded to GitHub and Netlify, then you change the file name to Seo on your local machine and upload it to GitHub and Netlify. Only when you modify an existing file’s case like this will errors occur.

Because your OS is case-insensitive, when you change seo to Seo, it won’t tell Git that the file name changed. Your Git and Netlify file names won’t change, but the code on them will change, so the bug occurs.

One thing to note: Git on your machine is usually case-insensitive by default. I saw someone on Stack Overflow suggest setting Git to case-sensitive using the command git config --local core.ignorecase false to make Git remember case changes, but this is a wrong suggestion and won’t solve the error above.

Setting Git to case-sensitive in a case-insensitive file system will cause strange situations. For example, when you change seo to Seo locally, if you run git status, you’ll see +Seo but not -seo, meaning both seo and Seo will appear on GitHub, showing that this setting cannot solve the errors that occur with Git’s default case-insensitive behavior.

How to solve

Just because it doesn’t happen often doesn’t mean it won’t happen. If it does, how do you solve it? You can follow this explanation, which has two methods:

Method 1:

    git mv -f seo Seo

Method 2:

1. Change the name from seo to SSS
2. Commit
3. Change SSS to Seo
4. Commit again

Customer service gamification

However, what interested me most about solving this problem was something else. Netlify doesn’t actually provide customer service for free members like me, but when you post on their forum, official technical staff might provide suggestions on the forum. I registered to solve this bug on my website.

Because it was my first post, my level and permissions were very low, so when I posted, I couldn’t upload more than 2 images. Then by doing various things, you get badges, such as: first time using Emoji, first time mentioning someone, three consecutive days on the forum, etc. In short, the system has bots constantly giving you feedback, encouraging you to ask good questions and answer questions, and then your level keeps rising. As your level rises, you gain new powers to do more advanced things. The whole process is a bit like playing a game, which is quite interesting.

I think this system encourages everyone to share discovered problems and solutions, making it easier for Netlify customers to find answers directly on their forum when they encounter problems, and it can greatly reduce Netlify’s customer service costs. This was actually the most impressive part of solving this problem. I don’t know—maybe gamification isn’t new in the tech world, but perhaps it’s worth other industries considering it.