Matomo Troubleshooting

Common Errors + Fixes (Real Issues)

Matomo Troubleshooting

New to Matomo or haven’t set it up yet? Before diving into troubleshooting, you may want to read my step-by-step guide: “What is Matomo and How to Set Up Matomo Locally.” It covers the basics of Matomo, local Docker setup, and initial configuration — which will make the issues discussed in this article much easier to understand and reproduce. Link: https://medium.com/p/3d92fcb8e4b4

Here are the errors that I faced during Matomo implementations

Error: Could not connect to DB

getaddrinfo for matomo-db failed

Fix:

• Make sure DB container name is matomo-db
• In Matomo setup, DB Server must be: matomo-db

MySQL Restarting / Unknown variable default-authentication-plugin

This happens when MySQL version is incompatible.

Fix: Use image: mysql:8.0 in yaml file Avoid 8.4

image: mysql:8.0

How to Track Events from Your App

After Matomo setup, add events in your app:

if (window._paq) {
  window._paq.push(['trackEvent', 'Planning', 'Plan A Landing Page View']);
}

You can track multiple events like:

_paq.push(['trackEvent', 'Plan A', 'Plan A Landing Page View']);
_paq.push(['trackEvent', 'Plan A', 'Plan A Details Page View']);

_paq.push(['trackEvent', 'Plan B', 'Plan B Landing Page View']);
_paq.push(['trackEvent', 'Plan B', 'Plan B Details Page View']);

Where to Verify Events in Matomo

After your app sends events, check them here:

✅ Behavior → Events

You will see:

• Top Event Categories
• Top Event Actions
• Top Event Names

✅ Real-Time:

• Visitors → Real-time → Events

This is the best place to confirm events instantly.

Thanks for Reading!

If you found this useful: Clap for the article, it helps others discover it Follow me for more practical guides on analytics, web development, and real-world engineering solutions Leave a comment if you’d like a deep dive into any specific Matomo feature

I regularly share hands-on content about: Web analytics & tracking NodeJS / Nest.js / React / Next.js implementations System design & real project learnings

Stay tuned more coming soon