Troubleshooting

Overview

This guide covers common issues you may encounter when self-hosting Umami and how to resolve them.

Before troubleshooting, check the GitHub Discussions and Issues for similar problems.

Installation Issues

Database Connection Errors

Error: DATABASE_URL is not defined

Cause: Missing DATABASE_URL environment variable.Solution:

# Create .env file
echo 'DATABASE_URL=postgresql://umami:password@localhost:5432/umami' > .env

# Or export environment variable
export DATABASE_URL=postgresql://umami:password@localhost:5432/umami

For Docker:

docker-compose.yml

environment:
  DATABASE_URL: postgresql://umami:umami@db:5432/umami

Error: Connection refused (ECONNREFUSED)

Cause: Cannot connect to PostgreSQL server.Diagnosis:

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U umami -h localhost -d umami

# Check port is listening
netstat -an | grep 5432

Solutions:

Start PostgreSQL:

sudo systemctl start postgresql

Check pg_hba.conf allows connections:

sudo nano /etc/postgresql/15/main/pg_hba.conf

Add:

host    all    all    127.0.0.1/32    md5

Check postgresql.conf:

sudo nano /etc/postgresql/15/main/postgresql.conf

Ensure:

listen_addresses = 'localhost'

Restart PostgreSQL:

sudo systemctl restart postgresql

Error: password authentication failed

Cause: Incorrect database credentials.Solution:

# Reset PostgreSQL password
sudo -u postgres psql
ALTER USER umami WITH PASSWORD 'new-password';
\q

# Update DATABASE_URL
DATABASE_URL=postgresql://umami:new-password@localhost:5432/umami

Error: database does not exist

Cause: Database not created.Solution:

# Create database
sudo -u postgres psql
CREATE DATABASE umami;
CREATE USER umami WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE umami TO umami;
\q

Build Failures

Error: Node.js version too old

Cause: Umami requires Node.js 18.18 or higher.Check version:

node --version

Solution:

# Using nvm
nvm install 18
nvm use 18

# Or update system Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Error: Prisma Client could not locate...

Cause: Prisma Client not generated.Solution:

# Generate Prisma Client
pnpm prisma generate

# Or rebuild from scratch
rm -rf node_modules .next generated
pnpm install
pnpm build

Error: ENOSPC - no space left on device

Cause: Insufficient disk space or inotify watches.Check disk space:

df -h

Increase inotify watches:

# Temporary
sudo sysctl fs.inotify.max_user_watches=524288

# Permanent
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Runtime Issues

Application Won’t Start

Error: Port already in use

Cause: Another process is using port 3000.Find process:

# Linux/Mac
lsof -i :3000

# Or
netstat -tulpn | grep 3000

Solutions:

Kill the process:

kill -9 <PID>

Use a different port:

PORT=3001 pnpm start

For Docker:

ports:
  - "3001:3000"

Container keeps restarting

Check logs:

docker compose logs umami

Common issues:

Database connection failed → Check DATABASE_URL
Migration error → Check migration logs
Out of memory → Increase container memory limit

Increase memory:

docker-compose.yml

services:
  umami:
    deploy:
      resources:
        limits:
          memory: 1G

502 Bad Gateway with reverse proxy

Cause: Proxy can’t connect to Umami.Nginx configuration:

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Test backend:

curl http://localhost:3000/api/heartbeat

Cannot login with admin/umami

Default credentials changed in v3.0:

Username: admin
Password: umami

Reset password:

# Using change-password script
pnpm change-password

# Or directly in database
psql -U umami umami

-- Hash for password 'newpassword'
UPDATE "user" 
SET password = '$2a$10$...' 
WHERE username = 'admin';

Session expires immediately

Cause: APP_SECRET not set or changing.Solution:

# Generate stable APP_SECRET
openssl rand -base64 32

# Add to .env
APP_SECRET=generated-secret-here

# Restart application

For multi-instance deployments:

# Use Redis for session storage
REDIS_URL=redis://localhost:6379

Infinite redirect loop

Cause: Reverse proxy SSL configuration.Nginx solution:

proxy_set_header X-Forwarded-Proto $scheme;

Umami configuration:

FORCE_SSL=1

Tracking Issues

Data Not Being Collected

Tracker script not loading

Check script loads:

curl https://your-domain.com/script.js

Browser console errors:

Open browser DevTools (F12)
Check Console tab for errors
Check Network tab for failed requests

Common issues:

Ad blocker blocking tracker
CORS error → Check ALLOWED_FRAME_URLS
Wrong website URL in tracking code

Test without ad blocker:Open in incognito/private mode

Events not appearing in dashboard

Verify tracking code:

<script defer src="https://analytics.yourdomain.com/script.js" 
        data-website-id="your-website-id"></script>

Check website ID:

Login to Umami
Go to Settings → Websites
Copy the correct website ID

Test data collection:

# Send test event
curl -X POST https://your-domain.com/api/send \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "payload": {
      "website": "your-website-id",
      "url": "/test",
      "hostname": "test.com"
    }
  }'

Check database:

SELECT COUNT(*) FROM website_event 
WHERE website_id = 'your-website-id';

Real-time data not updating

Cause: Cache or database connection issues.Clear cache:

# Restart application
docker compose restart umami
# or
pm2 restart umami

Check database connection:

# Docker
docker compose exec umami node -e "require('prisma').default.\$connect().then(() => console.log('Connected'))"

CORS Errors

CORS policy error in browser console

Error:

Access to fetch at 'https://analytics.example.com/api/send' from origin 'https://website.com' has been blocked by CORS policy

Cause: Umami’s CORS headers are permissive by default, but reverse proxy may override.Nginx solution:

location /api/send {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    
    # Don't override Umami's CORS headers
    proxy_hide_header Access-Control-Allow-Origin;
}

Verify CORS headers:

curl -H "Origin: https://website.com" \
     -H "Access-Control-Request-Method: POST" \
     -X OPTIONS \
     https://analytics.example.com/api/send

Should return:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, DELETE, POST, PUT

Performance Issues

Slow Dashboard

Dashboard takes long to load

Check database performance:

-- Find slow queries
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Optimize database:

VACUUM ANALYZE;
REINDEX DATABASE umami;

Check indexes:

pnpm prisma migrate status

For high volume, use ClickHouse:

CLICKHOUSE_URL=http://localhost:8123/umami

High memory usage

Check current usage:

# Docker
docker stats umami

# System
ps aux | grep node

Increase Node.js memory:

NODE_OPTIONS="--max-old-space-size=4096" pnpm start

For Docker:

docker-compose.yml

environment:
  NODE_OPTIONS: "--max-old-space-size=4096"
deploy:
  resources:
    limits:
      memory: 4G

High CPU usage

Check for long-running queries:

SELECT pid, age(clock_timestamp(), query_start), query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY query_start;

Optimize queries:

EXPLAIN ANALYZE SELECT ...;

Add indexes if needed:

CREATE INDEX idx_custom ON table_name(column_name);

Migration Issues

Migration Failures

Migration hangs or times out

Increase timeout:

DATABASE_URL="postgresql://...?connect_timeout=300&statement_timeout=300000"

Run manually with psql:

psql -U umami umami < prisma/migrations/XX_migration/migration.sql

Check for locks:

SELECT * FROM pg_locks WHERE NOT granted;

Migration error: relation already exists

Mark migration as applied:

pnpm prisma migrate resolve --applied migration_name

Or reset migration state:

-- Carefully review before running!
DELETE FROM _prisma_migrations WHERE migration_name = 'problematic_migration';

Docker Issues

Container Problems

Cannot remove container

Force remove:

docker rm -f umami
docker compose rm -f umami

Remove with volumes:

docker compose down -v

Image pull fails

Check network:

docker pull ghcr.io/umami-software/umami:latest

Use specific version:

image: ghcr.io/umami-software/umami:v3.0.3

Authenticate to GHCR:

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Volume permission issues

Fix ownership:

# Find volume location
docker volume inspect umami_postgres-data

# Fix permissions
sudo chown -R 999:999 /var/lib/docker/volumes/umami_postgres-data/_data

Network Issues

Reverse Proxy Problems

Assets not loading (404)

Nginx configuration:

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # Important for Next.js
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_cache_bypass $http_upgrade;
}

WebSocket connection failed

Enable WebSocket proxy:

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Diagnostic Commands

System Information

# Node.js version
node --version

# npm/pnpm version
pnpm --version

# PostgreSQL version
psql --version

# Database connection test
psql "$DATABASE_URL" -c "SELECT version();"

# Umami version
cat package.json | grep version

# Environment variables
env | grep -E "DATABASE_URL|PORT|NODE_ENV"

Docker Diagnostics

# Container status
docker compose ps

# Container logs
docker compose logs -f umami

# Execute command in container
docker compose exec umami sh

# Check environment variables
docker compose exec umami env

# Container resource usage
docker stats umami

Database Diagnostics

-- Table sizes
SELECT
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

-- Row counts
SELECT
  'website_event' as table,
  COUNT(*) as rows
FROM website_event
UNION ALL
SELECT 'session', COUNT(*) FROM session;

-- Migration status
SELECT * FROM _prisma_migrations ORDER BY finished_at DESC;

-- Active connections
SELECT count(*) FROM pg_stat_activity WHERE datname = 'umami';

Getting Help

GitHub Discussions

Ask questions and get community support

Discord

Chat with the community in real-time

GitHub Issues

Report bugs and request features

Documentation

Official documentation and guides

Creating a Bug Report

When reporting issues, include:

Environment:
- Umami version
- Node.js version
- PostgreSQL version
- Deployment method (Docker/source)
- Operating system
Steps to reproduce:
- What you did
- What you expected
- What actually happened

Logs:

# Application logs
docker compose logs umami > logs.txt

# Or for source installation
pnpm start 2>&1 | tee logs.txt

Database status:

pnpm prisma migrate status > migration-status.txt

Next Steps

Environment Variables

Review configuration options

PostgreSQL

Optimize database performance

Docker Deployment

Docker-specific issues

Migrations

Database migration troubleshooting

Deployment

Database

Operations

Troubleshooting

Overview

Installation Issues

Database Connection Errors

Build Failures

Runtime Issues

Application Won’t Start

Tracking Issues

Data Not Being Collected

CORS Errors

Performance Issues

Slow Dashboard

Migration Issues

Migration Failures

Docker Issues

Container Problems

Network Issues

Reverse Proxy Problems

Diagnostic Commands

System Information

Docker Diagnostics

Database Diagnostics

Getting Help

GitHub Discussions

Discord

GitHub Issues

Documentation

Creating a Bug Report

Next Steps

Environment Variables

PostgreSQL

Docker Deployment

Migrations

Build docs developers (and LLMs) love

Deployment

Database

Operations

​Overview

​Installation Issues

​Database Connection Errors

​Build Failures

​Runtime Issues

​Application Won’t Start

​Login Issues

​Tracking Issues

​Data Not Being Collected

​CORS Errors

​Performance Issues

​Slow Dashboard

​Migration Issues

​Migration Failures

​Docker Issues

​Container Problems

​Network Issues

​Reverse Proxy Problems

​Diagnostic Commands

​System Information

​Docker Diagnostics

​Database Diagnostics

​Getting Help

GitHub Discussions

Discord

GitHub Issues

Documentation

​Creating a Bug Report

​Next Steps

Environment Variables

PostgreSQL

Docker Deployment

Migrations

Build docs developers (and LLMs) love

Overview

Installation Issues

Database Connection Errors

Build Failures

Runtime Issues

Application Won’t Start

Login Issues

Tracking Issues

Data Not Being Collected

CORS Errors

Performance Issues

Slow Dashboard

Migration Issues

Migration Failures

Docker Issues

Container Problems

Network Issues

Reverse Proxy Problems

Diagnostic Commands

System Information

Docker Diagnostics

Database Diagnostics

Getting Help

Creating a Bug Report

Next Steps