Debugging Notion

Notion moves fast and sometimes bugs or issues can get in your way. “Notion is Buggy” is a thing we say a lot here at Notion Mastery. So what should you do when bugs happen or you think something may be broken?

Basic Debugging Techniques

👯‍♀️ Create a shareable “repro”

Something not working in a complex system? Try creating a “repro” (reproduction) that is simplified and highlights only the parts that are breaking. You could try replicating the same issue on a separate page or database. You could also try creating the same issue in a different workspace.

Benefits:

• Allows you to share with others to confirm bug.
• Allows you to share with Notion support staff.
• Rules out other issues such as bad setup or bad data.
• Makes it easier for people to confirm your issue if they don’t have to be caught up to speed on a really complex setup.

📶 Fix your internet!

You may see loading icons or slow-to-load pages. Notion is an online-only application, meaning if you do not have a stable internet connection, things may take time to load or fail to load properly. Applications and websites do not load property very frequently, so this is totally normal.

Check your internet connection speed and reliability. You may need to call your internet service provider (”ISP”) to help you troubleshoot your hardware or software involved in providing your service.

🔁 Reload!

• Try reloading/refreshing the browser or application. Oftentimes a simple refresh will “fix” things!
  • In most browsers, refreshing the page is performed with the ctrl/cmd + r keyboard shortcut.
  • In the desktop applications, you can use the same command to reload the application window (ctrl/cmd + r)

👀 Check Notion platform status!

Visit https://status.notion.so to investigate if there is any “downtime”. You can also follow @NotionStatus on Twitter.

Sometimes Notion’s upstream providers (the services Notion themselves use to provide the Notion experience) are having issues, which may mean that other websites and applications are slow or offline. TL;DR: it’s not always Notion’s fault!

You can subscribe to get updates on Notion’s status via email and text.

🤖 Reset Notion!

When you submit a support request to Notion, they will without a doubt ask you to “Reset” Notion first. In order to avoid additional back-and-forth with support, do this in advance to confirm your issue isn’t fixed by resetting the app. Then when you get around to filing a ticket you can say “I’ve already reset Notion and the issue persists.”

To read how to “Reset Notion” on your platform, click here.

🎫 Ask Notion for help! (”file a ticket”)

If you think something is “definitely broken”, you can click the “?” icon in the bottom right of Notion’s interface on any page. Keep in mind you will have to move your mouse to reveal this button so you can click it.

Select the Send us a message menu item and use the chat interface to send a message.

Notion uses Intercom for chat support, and it’s been know to be temperamental, so you can also send a support request to team@makenotion.com to achieve the same result via email.

⏰ Give it time!

Sometimes the best thing to do is move onto something else and try again later. You may find the issue results after a bit. Sometimes waiting 24 hours will be enough for the issue to resolve.

⚠️ Heavy tech jargon ahead! Feel free to skip the Advanced debugging section unless you want a deeper dive on debugging Notion.

Advanced debugging (read at your own risk!)

Notion runs in a browser, and, technically speaking, the desktop app is also browser-based. This is because the Notion app is built with Electron, a toolkit that allows developers to make applications with web technologies that are cross-platform.

This is not uncommon. Many apps you know and use use Electron: Slack, Twitch, WhatsApp, et al.

What does this mean for you? Some high-level points:

• There’s little functional or performance reasons for using the desktop app versus your browser.
• You can use a lot of the same tooling you might use in the browser to inspect and/or debug the application.

🧐 Using the inspector

In Google Chrome, Mozilla Firefox, and in the Notion desktop app, you can use the keyboard shortcut cmd/ctrl + option/alt + i to reveal the web inspector.

The inspectors look different from browser-to-browser, but most have similar features.

Here are three main things you might want to “inspect” while debugging:

1. Console – this will display messages logged by the application. It can also show you the requests being made by the application.
2. Elements – allows you to select HTML elements and inspect CSS used by Notion. This can be super handy when reporting bugs to Notion.
3. Network – Allows you to inspect Network traffic. Maybe the issue is in the communication between the Notion “client” and Notion’s backend services.

🍱 Elements

You can “poke around” (and even edit! be careful here!) the document object model (”DOM”) rendered by Notion to inspect HTML and CSS. For example, you might use this to discover what colors Notion is using.

Here’s a quick video showing the basics of how to use this:

🚦 Network traffic

The Network tab lets you view all the requests being made by Notion in “real-time”.

Above we see:

1. Requests that can be inspected, and,
2. Status codes

The MDN web docs tell us a bit about status codes:

1. Informational responses (100–199)
2. Successful responses (200–299)
3. Redirection messages (300–399)
4. Client error responses (400–499)
5. Server error responses (500–599)

So in the above screenshot, all the responses with a Status code of 200 tell us that things are “working as expected”. If you find any 4xx or especially 5xx errors, those would be really interesting to inspect or share with Notion support team!

Lastly, we can actually have a look at the response by clicking on any of those requests and clicking the Preview or Response tabs.

I’ve used this in the past to discover that search results were not being displayed properly in the app even though they were “found” via the request. This was helpful information for Notion’s support team.

1. Only show Fetch/XHR
2. Click a request to view…
3. …the payload that is returned from Notion’s API

---

Running into bugs and issues with software that runs your business can be incredibly frustrating. Knowing how to diagnose and even debug your own issues can save you a lot of time and provide helpful information to the software provider so they can fix issues more readily. Notion is no different!

🐛 Happy debugging!