Hossam Mourad

The Right Mindset for Fixing Software Bugs

April 08, 2022

You’re faced with a software bug, there are two routes you can take:

  1. Google for a fix -> apply it and verify it’s working -> move on
  2. Google for a fix -> apply it -> Scratch your head for some time because the fix is actually working well but you have no idea why -> play with the fix for a bit, try to break it -> leads you to read more about the source of the issue -> your mind is at peace now -> move on

The direction you will take does not actually matter that much for fixing this particular issue. Let’s be honest, these days with all these online communities in existence, there is most definitely someone else who faced the same issue and a web page somewhere on the internet for any given error you may encounter.

What really matters is training your mind to question things, to not accept an answer if it doesn’t make sense, to have a mindset that can make you understand the tool you’re using on a deeper level. The benefits gained from this mind shift will make you a better software craftsman. At least it will make you better at answering the questions you’re going to get from that Staff Engineer who actually knows their craft and noticed that you missed something while applying your fix that may break other parts of the software.

Let me give you an example, it’s frontend-focused example, sorry if it doesn’t make sense to you.


A Chart is rendered using SVG on a page. A “Download” button for that SVG was not working as expected, throwing this error all of a sudden:

Uncaught ReferenceError: Buffer is not defined

This download button used to work fine before, but recently it stopped and threw that error.

Technical Context:

  • This front-end app is using Webpack (v.5 to be specific)
  • Buffer is a Node core module used to convert really any kind of data to a stream of binary data

I started investigating the issue by looking at the error stack trace but it wasn’t that helpful. How can I know more about the error if the module itself is not defined in the first place? I now need to figure out why the browser suddenly is not able to find the Buffer module.

I went to the browser console and typed Buffer just to be sure about what I’m dealing with here, I got this:

browser console buffer

This is good and makes sense. Buffer is a NodeJS module. The browser should not be able to utilize it. I’m now sure that the Buffer module is not a browser API. So it must come from Node’s side and our client-side app is able to utilize it somehow.

Then I did what everybody else would do when they are in the same situation. I Googled it and found this:

StackOverflow fix 1

It looked reasonably simple and straightforward, so I gave it a shot, copy-pasted the code and tried to run the app, and it worked.

This is where I could have stopped. The fix is working and I can now push it in a PR so my team can move on and work on other interesting things. But to be honest, I didn’t have any idea what was going on. I didn’t understand why the app was able to work with Buffer before, but now it’s broken and needed that specific fix to work again.

I spent around an hour trying to figure out what was happening, and it eventually made sense. Long story short; it’s all about Webpack. Webpack v.4 used to automatically polyfill Node.js core modules, but starting from v.5 they removed this behavior. Developers need to explicitly polyfill any NodeJS core modules they want to use in their app.

This extra hour I spent was not wasted. I was at least able to explain in the PR why Buffer is not working suddenly and educate others who didn’t realize what Webpack was doing in the background for NodeJS core modules. I understood Webpack v.4 better and discovered that it actually can be quite powerful when it comes to automatically polyfilling Node.js core modules (not ideal, but helpful in some cases for sure if I want to utilize a NodeJS core module in a client-side app).

This reminds me of the following paragraph from this fantastic article:

Intelligent people simply aren’t willing to accept answers that they don’t understand — no matter how many other people try to convince them of it, or how many other people believe it, if they aren’t able to convince them selves of it, they won’t accept it.