Umami Troubleshooting | OpsBlu Docs

Umami Troubleshooting

Troubleshoot and debug Umami issues — common errors, data discrepancies, and step-by-step diagnostic procedures.

Common Issues and Solutions

No Data Appearing in Dashboard

Symptoms

  • Dashboard shows zero pageviews
  • Real-time visitors count is zero
  • Events not appearing

Diagnostic Steps

1. Verify Script Installation

Check that the Umami script is correctly installed:

<!-- Umami Cloud -->
<script async src="https://cloud.umami.is/script.js"
  data-website-id="your-website-id"></script>

<!-- Self-Hosted -->
<script async src="https://your-umami-instance.com/script.js"
  data-website-id="your-website-id"></script>

2. Confirm Website ID

// Check in browser console
const script = document.querySelector('script[data-website-id]');
console.log('Website ID:', script?.getAttribute('data-website-id'));
// Should match ID in Umami dashboard

3. Check if Umami is Loaded

// Verify umami object exists
console.log(typeof umami);
// Should output 'object'

// Test tracking
umami.track('test-event');
console.log('Test event sent');

4. Verify Network Requests

  • Open browser DevTools (F12)
  • Go to Network tab
  • Look for POST request to /api/send
  • Check response status (should be 200)

5. Check for Errors

Common issues:

  • 404: Script URL is incorrect
  • 403/401: Website ID doesn't exist or is disabled
  • CORS errors: Self-hosted configuration issue
  • Ad blockers: May block Umami script

Quick Fixes

// Diagnostic script
console.log('=== Umami Diagnostics ===');
console.log('Loaded:', typeof umami !== 'undefined');

const script = document.querySelector('script[data-website-id]');
console.log('Script URL:', script?.src);
console.log('Website ID:', script?.getAttribute('data-website-id'));
console.log('Domain:', window.location.hostname);

// Test tracking
if (typeof umami !== 'undefined') {
  umami.track('diagnostic-test', {
    test: true,
    timestamp: new Date().toISOString()
  });
  console.log('Test event sent successfully');
} else {
  console.error('Umami not loaded');
}

Events Not Recording

Troubleshooting Event Tracking

1. Verify Event Syntax

// Correct syntax
umami.track('event_name');
umami.track('event_name', { property: 'value' });

// Common mistakes
umami.track();  // Missing event name
umami.track('event name');  // Spaces in name (use underscores)
umami.track('event', 'value');  // Properties must be object

2. Check Events Appear in Dashboard

  • Navigate to Events tab in Umami
  • Filter by event name
  • Check date range includes today
  • Verify events appear within 1-2 minutes

3. Debug Event Tracking

// Test event with logging
function testEvent(name, data) {
  console.log('Tracking event:', name, data);
  umami.track(name, data);
  console.log('Event sent');
}

testEvent('test_event', { test: true });

// Check browser network tab for POST to /api/send

4. Data Attribute Events Not Working

<!-- Verify data attribute syntax -->
<button data-umami-event="button_clicked">Correct</button>

<!-- Common mistakes -->
<button data-umami="button_clicked">Wrong - missing '-event'</button>
<button umami-event="button_clicked">Wrong - missing 'data-'</button>

Self-Hosting Issues

Database Connection Problems

1. Check Database Connection

# Test database connectivity
psql -h localhost -U umami -d umami

# Or for MySQL
mysql -h localhost -u umami -p umami

2. Verify Environment Variables

# .env file should contain:
DATABASE_URL=postgresql://user:password@localhost:5432/umami
# or
DATABASE_URL=mysql://user:password@localhost:3306/umami

HASH_SALT=your-random-salt-string

3. Check Database Migrations

# Run migrations
npm run build-db

# Check migration status
npm run check-db

Server Not Starting

1. Check Server Logs

# View logs
npm run start

# Check for errors
journalctl -u umami  # if using systemd
docker logs umami    # if using Docker

2. Common Startup Errors

# Database connection failed
Error: connect ECONNREFUSED 127.0.0.1:5432
Solution: Check DATABASE_URL and database is running

# Port already in use
Error: listen EADDRINUSE: address already in use :::3000
Solution: Change PORT in .env or stop other service

# Missing dependencies
Error: Cannot find module 'next'
Solution: Run npm install

3. Docker Issues

# Check Docker container status
docker ps -a | grep umami

# View container logs
docker logs umami

# Restart container
docker restart umami

# Check Docker Compose configuration
docker-compose config

# Rebuild and restart
docker-compose down
docker-compose up -d --build

CORS Errors (Self-Hosted)

1. Configure CORS Headers

For Nginx:

location /api/ {
  proxy_pass http://localhost:3000;
  add_header Access-Control-Allow-Origin *;
  add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
  add_header Access-Control-Allow-Headers "Content-Type";
}

For Apache:

<Location /api/>
  Header set Access-Control-Allow-Origin "*"
  Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
  Header set Access-Control-Allow-Headers "Content-Type"
</Location>

2. Environment Configuration

# .env file
CORS_MAX_AGE=86400
ALLOWED_ORIGINS=https://yoursite.com,https://www.yoursite.com

Performance Issues

Dashboard Loading Slowly

1. Database Optimization

-- PostgreSQL: Vacuum and analyze
VACUUM ANALYZE;

-- Check table sizes
SELECT relname, pg_size_pretty(pg_total_relation_size(relid))
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

2. Index Optimization

# Check if indexes exist
npm run check-db

# Rebuild indexes if needed
npm run build-db

3. Data Retention

// Configure data retention in database
// Delete old data to improve performance
DELETE FROM event WHERE created_at < NOW() - INTERVAL '90 days';
DELETE FROM pageview WHERE created_at < NOW() - INTERVAL '90 days';

High Server Load

1. Optimize Configuration

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm start

# Use process manager like PM2
pm2 start npm --name umami -- start
pm2 scale umami 4  # Run 4 instances

2. Use CDN for Script

<!-- Serve script.js through CDN -->
<script async src="https://cdn.yoursite.com/script.js"
  data-website-id="your-id"></script>

3. Database Connection Pooling

// Increase connection pool size
// DATABASE_URL with pool parameters
postgresql://user:pass@localhost/umami?pool_max=20

Website Not Showing in Dashboard

Troubleshooting

1. Verify Website is Added

  • Login to Umami dashboard
  • Check Settings > Websites
  • Ensure website is not disabled
  • Verify domain matches exactly

2. Create Website if Missing

# Using Umami API
curl -X POST https://your-umami.com/api/websites \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Website","domain":"example.com"}'

3. Check Website ID Matches

The data-website-id in your script must match the ID shown in dashboard.

Real-Time Data Not Updating

Solutions

1. Clear Browser Cache

// Force refresh dashboard
location.reload(true);

// Clear service worker cache
navigator.serviceWorker.getRegistrations().then(registrations => {
  registrations.forEach(registration => registration.unregister());
});

2. Check WebSocket Connection (if using real-time)

// Verify WebSocket connection
console.log('WebSocket:', window.WebSocket);

3. Verify Server Time

# Check server time is correct
date

# Sync time if needed
ntpdate pool.ntp.org

Privacy and Ad Blocker Issues

Ad Blockers Blocking Umami

1. Use Custom Domain

<!-- Instead of: -->
<script src="https://umami-instance.com/script.js"></script>

<!-- Use subdomain: -->
<script src="https://analytics.yoursite.com/script.js"></script>

2. Proxy Through Your Domain

Nginx configuration:

location /stats/ {
  proxy_pass https://your-umami.com/;
  proxy_set_header Host $host;
}

Update script:

<script async src="/stats/script.js"
  data-website-id="your-id"></script>

3. Rename Script File

# Copy and rename script.js
cp public/script.js public/analytics.js

# Update your tracking code
<script async src="https://your-umami.com/analytics.js"
  data-website-id="your-id"></script>

Debugging Tools

Enable Debug Mode

// Add debug parameter to script
<script async src="https://cloud.umami.is/script.js"
  data-website-id="your-id"
  data-auto-track="false"
  data-cache="false"></script>

// Manual tracking with logging
umami.track('test', { debug: true });
console.log('Tracking test event');

Browser Console Diagnostics

// Comprehensive diagnostic check
console.log('=== Umami Diagnostics ===');
console.log('Script loaded:', typeof umami !== 'undefined');
console.log('Website ID:', document.querySelector('[data-website-id]')?.getAttribute('data-website-id'));
console.log('Current URL:', window.location.href);
console.log('Hostname:', window.location.hostname);
console.log('User Agent:', navigator.userAgent);

// Test tracking
if (typeof umami !== 'undefined') {
  umami.track('diagnostic_test', {
    test: true,
    url: window.location.href,
    timestamp: new Date().toISOString()
  });
  console.log('✓ Test event sent');
} else {
  console.error('✗ Umami not loaded');
}

Getting Additional Help

Support Resources

  • Documentation: umami.is/docs
  • GitHub Issues: github.com/umami-software/umami/issues
  • Discord Community: discord.gg/4dz4zcXYrQ
  • Discussions: github.com/umami-software/umami/discussions

Before Requesting Help

Gather this information:

  1. Umami version (check package.json or dashboard footer)
  2. Self-hosted or Umami Cloud
  3. Database type and version (PostgreSQL/MySQL)
  4. Node.js version
  5. Browser and version
  6. Console errors (screenshots)
  7. Steps to reproduce
  8. Server logs (if self-hosted)

Escalation Path

  1. Search existing GitHub issues
  2. Check documentation and discussions
  3. Ask in Discord community
  4. Open GitHub issue with details
  5. For Umami Cloud: Email support@umami.is (paid plans)
Back to top