Uptime Kuma User Guide

Uptime Kuma is a self-hosted monitoring tool that watches the health of your websites, APIs, servers, databases, containers, game servers, and other network endpoints. When something breaks, it alerts you through 93 notification channels. You run it on your own machine, inside Docker, or on a small VPS. It gives you a modern dashboard, public status pages, and fine-grained alerting with zero telemetry and zero external dependencies beyond what you configure.

This guide is for end users and operators who want to install, configure, and run Uptime Kuma day to day. If you are deploying at scale, customizing source, hardening security, or contributing, read the Admin Guide.

Note

This guide documents Uptime Kuma 2.2.1 (commit 43b143c, 2026-04-17). Uptime Kuma 2.x is a significant revision of 1.x; all version tags, defaults, and screenshots below refer to the 2.x line unless stated otherwise.

1. Quick Start

Get a monitor running in under three minutes.

1.1 Start the server

Docker Compose (recommended)

mkdir uptime-kuma && cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

Docker run (single container)

docker run -d --restart=always -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

Node.js (bare metal)

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
node server/server.js

Expected output (Docker):

[+] Running 1/1
 ✔ Container uptime-kuma  Started

1.2 Open the web UI

Point a browser at:

http://localhost:3001

The first visit shows the setup wizard.

1.3 Finish first-time setup

1. Choose a database backend (SQLite is the default and recommended for most users).
2. Create the admin username and password.
3. You land on an empty dashboard.

1.4 Add your first monitor

1. Click Add New Monitor.
2. Pick HTTP(s) as the monitor type.
3. Enter a friendly name (e.g., My Website).
4. Enter the URL (e.g., https://example.com).
5. Leave Heartbeat Interval at 60 seconds.
6. Click Save.

Within one heartbeat cycle you see a green status dot and the first data point on the ping chart.

Tip

The first heartbeat fires immediately after saving — you do not have to wait 60 seconds to see whether a monitor is configured correctly.

2. Installation

Uptime Kuma ships as a Docker image, a Node.js application, or an embedded package with optional MariaDB. Choose the method that matches your environment.

2.1 Supported platforms

Warning

Filesystems like NFS (Network File System) are not supported for the /app/data volume. Use a local directory or a Docker named volume. Running on NFS causes SQLite corruption and random crashes.

2.2 Requirements

2.3 Docker Compose (recommended)

Create a working directory, download the sample Compose file, and start the stack.

mkdir uptime-kuma && cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

The reference compose.yaml shipped with the repo is:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

Note

The bind mount ./data:/app/data stores the SQLite database, uploaded icons, screenshots, and Docker TLS certificates. Back up this directory to preserve your monitors and their history.

Docker Compose with Docker socket monitoring

If you want to monitor Docker containers, mount the Docker socket:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "3001:3001"

Docker Compose with TLS

If you want Uptime Kuma to serve HTTPS directly (without a reverse proxy):

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - ./certs:/certs:ro
    ports:
      - "3001:3001"
    environment:
      - UPTIME_KUMA_SSL_KEY=/certs/key.pem
      - UPTIME_KUMA_SSL_CERT=/certs/cert.pem

2.4 Docker run (single container)

docker run -d --restart=always -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

To expose the UI only on localhost (for example, behind a reverse proxy):

docker run -d --restart=always -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

2.5 Non-Docker (Node.js + PM2)

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

npm run setup checks out the tagged 2.2.1 release, installs production dependencies with npm ci --omit dev --no-audit, and downloads the pre-built frontend.

Run once to verify:

node server/server.js

Expected output:

Welcome to Uptime Kuma
Your Node.js version: 20.x.x
...
[INFO] server: Listening on 3001

Then supervise with PM2:

npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
pm2 startup && pm2 save

Useful PM2 commands:

pm2 monit              # Live console
pm2 logs uptime-kuma   # Tail logs
pm2 restart uptime-kuma
pm2 stop uptime-kuma

2.6 Windows installation (Node.js)

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
node server/server.js

For persistent service on Windows, consider using NSSM or PM2 on Windows:

npm install pm2 -g
pm2 start server/server.js --name uptime-kuma
pm2 save
pm2-startup install

2.7 Updating Uptime Kuma

Docker:

docker pull louislam/uptime-kuma:2
docker compose down && docker compose up -d

Node.js:

cd uptime-kuma
git pull
npm run setup
pm2 restart uptime-kuma

Important

Always back up ./data/ (or your Docker volume) before upgrading. Database migrations run automatically and are not reversible.

2.8 Verify the install

• docker ps or pm2 status shows the process running.
• curl -I http://localhost:3001 returns HTTP/1.1 302 Found (redirect to /dashboard or /setup).
• The web UI loads at http://localhost:3001.
• You completed the setup wizard and created an admin account.

3. Configuration

3.1 First-time database setup

On first boot (or when the data directory is empty), Uptime Kuma starts a setup server that asks two questions before the main application comes up.

Choose a database backend

SQLite files live at ./data/kuma.db by default. Configuration is written to ./data/db-config.json after the wizard.

Important

If you provide the UPTIME_KUMA_DB_TYPE environment variable, the setup wizard is skipped and the value is written straight to db-config.json. This is the recommended path for container automation and CI/CD pipelines.

Create the admin account

Enter a username and a strong password. Uptime Kuma rejects weak passwords with:

Password is too weak, please use a stronger password.

Minimum strength is validated by the check-password-strength library; aim for a mix of length, upper/lowercase, digits, and symbols.

After the wizard, Uptime Kuma restarts automatically (same port) and presents the normal login screen.

3.2 Environment variables (user-facing)

All environment variables are optional. Set them in your docker-compose.yml, .env file, or shell before starting the server.

Database-specific variables (UPTIME_KUMA_DB_TYPE, UPTIME_KUMA_DB_HOSTNAME, UPTIME_KUMA_DB_PORT, UPTIME_KUMA_DB_NAME, UPTIME_KUMA_DB_SOCKET, UPTIME_KUMA_DB_PASSWORD, UPTIME_KUMA_DB_PASSWORD_FILE) are covered in the Admin Guide.

3.3 Command-line flags

Flags can be passed directly to node server/server.js:

3.4 General settings

Navigate to Settings in the top-right menu. Key panels:

3.5 Timezone configuration

Set the server timezone via the TZ environment variable:

environment:
  - TZ=Europe/London

Per-user timezone is chosen under Settings and only affects how timestamps render in the UI. Invalid timezones are rejected with Invalid timezone:.

3.6 Search engine indexing

Under Settings → General, toggle Search Engine Indexing. When disabled, the robots.txt response changes from allowing all to:

User-agent: *
Disallow: /

3.7 Entry page

Under Settings → General, set the entry page. You can make the root URL (/) redirect to:

• The dashboard (default)
• A specific status page (e.g., statusPage-public)

If a custom domain is mapped to a status page, that mapping takes priority over this setting.

4. Core Usage

4.1 Dashboard overview

The dashboard is split into three areas:

• Left sidebar — list of monitors, grouped or sorted, with search and filter.
• Main pane — details of the selected monitor: status, ping chart, event list, certificate info, response-time graph, and uptime stats for 24 h, 30 d, 1 y, and all-time.
• Top bar — add monitor, theme toggle, language switch, and settings.

4.2 Monitor types

Uptime Kuma ships with 30+ monitor types. Each type checks a different kind of service.

HTTP / HTTPS monitors

Network monitors

Database monitors

Messaging / queue monitors

Infrastructure monitors

Protocol monitors

Special monitors

Tip

If you need HTTP plus a response-body assertion, pick HTTP(s) - Keyword or HTTP(s) - JSON Query rather than building your own script. The built-ins already handle retries, heartbeats, and notifications.

4.3 Adding a monitor

Click Add New Monitor. Choose a type, fill the type-specific fields, set timing, then save.

Common fields (all monitor types)

HTTP-specific fields

DNS-specific fields

Database-specific fields (MySQL, PostgreSQL, MSSQL, Oracle)

4.4 Monitor conditions

Uptime Kuma 2.x introduced a condition expression system. Instead of simple keyword matching, you can build complex conditions with operators:

String operators: Equals, Not Equals, Contains, Not Contains, Starts With, Not Starts With, Ends With, Not Ends With.

Numeric operators: Equals, Not Equals, Less Than, Greater Than, Less Than or Equal To, Greater Than or Equal To.

Conditions can be grouped with AND/OR logic (via ConditionExpressionGroup). This is used by DNS monitors, database query monitors, and SNMP monitors among others.

4.5 Pausing, resuming, editing, deleting

• Pause — the monitor stops firing heartbeats and notifications until resumed.
• Resume — resumes heartbeats from the next cycle.
• Edit — change any field. Changes take effect on the next heartbeat.
• Delete — removes the monitor and all heartbeat history permanently.
• Clone — duplicates the monitor configuration with a new name.

Caution

Delete cannot be undone. Heartbeats, certificate history, and related notification logs are permanently purged. Export your data first if you need to keep historical records.

4.6 Tags

Tags group related monitors without nesting them. Create tags in Settings → Tags, then attach them when editing a monitor. Each tag has:

• A name
• A color (displayed as a colored pill on the dashboard)
• An optional value per monitor (e.g., tag "Environment" with value "production")

Tags appear on the dashboard and can filter the monitor list.

4.7 Groups

A Group monitor is a parent that aggregates the status of its children.

• Its own status is down if any child is down (logical OR across children).
• Useful for a "website" that comprises web + API + database.
• Pausing the group does not pause the children (community-tracked behavior, issue #7242).
• Groups can be nested (a group can contain other groups).

4.8 Incidents

From the Status Page editor, post a short incident notice (title + content). Incidents appear on the public status page with a timestamp.

• Use for scheduled maintenance, known outages, or post-mortem recaps.
• Incidents do not change monitor state; they are purely informational overlays.
• The status page validates that both title and content are provided (Please input title / Please input content).

4.9 Maintenance windows

Create maintenance windows to silence notifications and mark monitors as "in maintenance" on a recurring schedule.

Attach monitors and status pages to the maintenance. During the window, monitors show a wrench icon and notifications are suppressed. Invalid dates produce Invalid start date or Invalid end date.

5. Common Tasks

5.1 Monitor a public website

1. Add an HTTP(s) monitor.
2. URL: https://example.com.
3. Accepted Status Codes: 200-299.
4. Heartbeat Interval: 60.
5. Retries: 2, Retry Interval: 60.
6. Attach a Slack or email notification channel.
7. Save.

5.2 Monitor an internal API with JSON assertion

1. Add an HTTP(s) - JSON Query monitor.
2. URL: https://api.internal/healthz.
3. JSON Path / Expression: status (JSONata syntax).
4. Expected Value: ok.
5. Add an auth header under HTTP Options → Headers (e.g., {"Authorization": "Bearer <token>"}).
6. Save.

5.3 Monitor a TCP service

1. Add a TCP monitor.
2. Hostname: db.internal.
3. Port: 5432.
4. Heartbeat: 30 seconds.
5. Save.

5.4 Monitor DNS resolution

1. Add a DNS monitor.
2. Hostname: example.com.
3. DNS Resolver Server: 8.8.8.8 (or leave blank for system default).
4. Record Type: A.
5. Add a condition: the resolved value must contain your expected IP.
6. Save.

Warning

DNS monitors with long TXT records (such as DKIM keys) may fail condition evaluation. This is a known issue tracked under #7280. Consider using a Contains condition instead of exact match for long TXT records.

5.5 Push monitor from a script (passive)

Uptime Kuma can be the receiver — your script pushes a heartbeat on a schedule.

1. Add a Push monitor. Copy the generated Push URL.
2. The URL format is: https://your-kuma/api/push/<token>?status=up&msg=OK&ping=
3. Both GET and POST are accepted.

Push URL parameters

Bash + curl

#!/bin/bash
PUSH_URL="https://example.com/api/push/key?status=up&msg=OK&ping="
INTERVAL=60

while true; do
    curl -s -o /dev/null $PUSH_URL
    echo "Pushed!"
    sleep $INTERVAL
done

Python

import urllib.request
import time

push_url = "https://example.com/api/push/key?status=up&msg=OK&ping="
interval = 60

while True:
    urllib.request.urlopen(push_url)
    print("Pushed!\n")
    time.sleep(interval)

PowerShell

$pushURL = "https://example.com/api/push/key?status=up&msg=OK&ping="
$interval = 60

while ($true) {
    $res = Invoke-WebRequest -Uri $pushURL
    Write-Host "Pushed!"
    Start-Sleep -Seconds $interval
}

JavaScript (Node.js >= 18, Deno, Bun)

const pushURL = "https://example.com/api/push/key?status=up&msg=OK&ping=";
const interval = 60;

const push = async () => {
    await fetch(pushURL);
    console.log("Pushed!");
};

push();
setInterval(push, interval * 1000);

TypeScript (Deno, Bun, ts-node)

const pushURL: string = "https://example.com/api/push/key?status=up&msg=OK&ping=";
const interval: number = 60;

const push = async () => {
    await fetch(pushURL);
    console.log("Pushed!");
};

push();
setInterval(push, interval * 1000);

Go

package main

import (
	"fmt"
	"net/http"
	"time"
)

func main() {
	const PushURL = "https://example.com/api/push/key?status=up&msg=OK&ping="
	const Interval = 60

	for {
		_, err := http.Get(PushURL)
		if err == nil {
			fmt.Println("Pushed!")
		}
		time.Sleep(Interval * time.Second)
	}
}

Java

import java.net.HttpURLConnection;
import java.net.URL;

class PushMonitor {
    public static final String PUSH_URL = "https://example.com/api/push/key?status=up&msg=OK&ping=";
    public static final int INTERVAL = 60;

    public static void main(String[] args) {
        while (true) {
            try {
                URL url = new URL(PUSH_URL);
                HttpURLConnection con = (HttpURLConnection) url.openConnection();
                con.setRequestMethod("GET");
                con.getResponseCode();
                con.disconnect();
                System.out.println("Pushed!");
            } catch (Exception e) {
                e.printStackTrace();
            }
            try {
                Thread.sleep(INTERVAL * 1000);
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
}

C#

using System;
using System.Net;
using System.Threading;

class PushMonitor
{
    const string PushURL  = "https://example.com/api/push/key?status=up&msg=OK&ping=";
    const int Interval = 60;

    static void Main(string[] args)
    {
        while (true)
        {
            WebClient client = new WebClient();
            client.DownloadString(PushURL);
            Console.WriteLine("Pushed!");
            Thread.Sleep(Interval * 1000);
        }
    }
}

PHP

<?php
const PUSH_URL = "https://example.com/api/push/key?status=up&msg=OK&ping=";
const interval = 60;

while (true) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, PUSH_URL);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_exec($ch);
    curl_close($ch);
    echo "Pushed!\n";
    sleep(interval);
}

Docker (pre-built push container)

docker run -d --restart=always --name uptime-kuma-push \
  louislam/uptime-kuma:push \
  "https://example.com/api/push/key?status=up&msg=OK&ping=" 60

5.6 Monitor a Docker container

1. Settings → Docker Hosts → Setup Docker Host.
2. Choose connection type:
   • Unix socket: /var/run/docker.sock (mount into the container with -v /var/run/docker.sock:/var/run/docker.sock:ro).
   • TCP: tcp://docker-host:2376 with optional TLS.
3. Test and save.
4. Add a Docker Container monitor and pick the host plus the container name.

5.7 Monitor a game server

1. Add a GameDig monitor.
2. Game type: pick from the GameDig catalog (Minecraft, Valheim, Counter-Strike, etc.).
3. Host / Port.
4. Save. A probe is issued every heartbeat.

For Steam servers specifically, use the Steam Game Server type with the Steam API key configured.

5.8 Monitor a database

MySQL / MariaDB

1. Add a MySQL monitor.
2. Enter hostname, port (default 3306), username, password, database name.
3. Optionally add a query (e.g., SELECT 1). If the query returns results not meeting conditions, the monitor goes down.
4. Save.

PostgreSQL

1. Add a PostgreSQL monitor.
2. Enter connection string or individual fields.
3. Optional query with conditions.
4. Save.

MongoDB

1. Add a MongoDB monitor.
2. Enter the connection string (e.g., mongodb://user:pass@host:27017/dbname).
3. Optionally add a MongoDB command. If the command fails, MongoDB command failed is reported.
4. Save.

Redis

1. Add a Redis monitor.
2. Enter hostname and port (default 6379).
3. Uptime Kuma sends a PING command and expects PONG.
4. Save.

5.9 Monitor an MQTT broker

1. Add an MQTT monitor.
2. Enter the MQTT broker URL (e.g., mqtt://broker.example.com:1883).
3. Choose a check type: Keyword or JSON Query.
4. Provide the topic to subscribe to and the expected message content.
5. Save.

Note

MQTT monitors currently do not accept mqtts:// URLs directly (issue #7286). Use mqtt:// with the appropriate port for TLS-wrapped connections, or configure a proxy.

5.10 Monitor with headless browser (Real Browser)

1. Configure a remote browser: Settings → Remote Browsers → Add.
2. Enter the Chromium WebSocket endpoint (e.g., ws://chromium:3000).
3. Test and save.
4. Add a Real Browser monitor. Select the remote browser.
5. Enter the URL. Uptime Kuma renders the page in headless Chromium.

This catches JavaScript-dependent failures that HTTP monitors miss (SPA apps, dynamic content).

If no Chromium executable is found: Chromium not found, please specify Chromium executable path in the settings page.

5.11 Monitor a systemd service or Windows service

1. Add a System Service monitor.
2. Enter the service name (e.g., nginx on Linux, W3SVC on Windows).
3. Save.

Service names must contain only alphanumeric characters and certain special characters. Invalid names produce Invalid service name.

System service monitoring is only supported on Linux (systemd) and Windows. Other platforms produce System Service monitoring is not supported on <platform>.

5.12 Monitor via Tailscale

1. Add a Tailscale Ping monitor.
2. Enter the Tailscale hostname or IP of the peer.
3. Save.

The Tailscale CLI must be available on the host running Uptime Kuma. Errors include:

• Ping timed out — peer is unreachable.
• Nonexistant or inaccessible due to ACLs — Tailscale ACLs block the connection.
• Tailscale only works if used on other machines — you cannot ping yourself.

5.13 Monitor with SNMP

1. Add an SNMP monitor.
2. Enter hostname, port (default 161), community string (v1/v2c) or username (v3).
3. Enter the OID to poll.
4. Set conditions on the returned value.
5. Save.

For SNMPv3: SNMPv3 username is required.

5.14 Monitor SMTP servers

1. Add an SMTP monitor.
2. Enter hostname and port (default 25, or 587 for submission, 465 for SMTPS).
3. Optionally enable STARTTLS verification.
4. Save.

If the SMTP greeting fails: SMTP connection doesn't...

5.15 Monitor with SIP OPTIONS

1. Add a SIP-Options monitor.
2. Enter the SIP URI target.
3. Uptime Kuma uses sipsak to send an OPTIONS probe.
4. Save.

Requires sipsak installed on the host. No output from sipsak indicates the binary is missing or the target is unreachable.

5.16 Monitor with Globalping

1. Add a Globalping monitor.
2. Choose the check type: Ping, HTTP, DNS, or Traceroute.
3. Enter the target.
4. Select probe locations (continents, countries, or specific probes).
5. Save.

Globalping distributes checks across worldwide probes. Rate-limiting by the Globalping API produces Failed to create measurement errors. Consider adding a Globalping API token under the monitor settings.

5.17 Monitor gRPC services

1. Add a gRPC - Keyword monitor.
2. Enter the gRPC server address and port.
3. Specify the service name and method.
4. Enter the proto file content or URL.
5. Set the keyword to match in the response.
6. Save.

5.18 Monitor WebSocket endpoints

1. Add a WebSocket Upgrade monitor.
2. Enter the WebSocket URL (e.g., wss://echo.websocket.org).
3. The monitor attempts the WebSocket upgrade handshake.
4. Save.

5.19 Build a status page for customers

1. Status Pages → New Status Page.
2. Slug: e.g., public (only letters, numbers, hyphens). Invalid slugs produce Invalid Slug.
3. Select the monitors to expose in groups/sections.
4. Upload a PNG logo (Only allowed PNG logo.).
5. Set a title, description, and optional custom footer.
6. Enable Show Certificate Expiry, Show Tags as desired.
7. Save. Public URL: https://your-kuma/status/public.
8. (Optional) Map a custom domain under Settings → Domain Names.

Status page endpoints

Custom domain for a status page

1. Point your DNS A record to your Uptime Kuma server IP.
2. In Settings → Domain Names, add the domain and map it to the status page slug.
3. When a request arrives on that domain, Uptime Kuma serves the mapped status page directly.

5.20 Set up a weekly maintenance window

1. Maintenance → New Maintenance.
2. Title: "Weekly Server Maintenance".
3. Strategy: Recurring: Day of Week.
4. Weekday: Sunday; Start: 03:00; End: 04:00.
5. Attach the affected monitors and status pages.
6. Save. Notifications are suppressed during the window.

5.21 Set up a monthly maintenance window

1. Maintenance → New Maintenance.
2. Strategy: Recurring: Day of Month.
3. Day: 1st; Start: 02:00; End: 04:00.
4. Attach monitors.
5. Save.

5.22 Set up a cron-based maintenance window

1. Maintenance → New Maintenance.
2. Strategy: Cron.
3. Cron expression: 0 3 * * 0 (every Sunday at 3 AM).
4. Duration: 60 minutes.
5. Save.

5.23 Create and use tags

1. Settings → Tags → Add Tag.
2. Name: Production, Color: red.
3. Add another: Staging, Color: yellow.
4. Edit monitors and assign tags with optional values (e.g., tag Region, value us-east-1).
5. Use the tag filter on the dashboard to view only production monitors.

5.24 Set up notification channels

1. Settings → Notifications → Setup Notification.
2. Pick a provider from the dropdown (93 available).
3. Fill provider-specific fields.
4. Click Test to send a sample alert.
5. Optionally Apply on all existing monitors.
6. Save.

5.25 Configure Discord notifications

1. In Discord, create a webhook in your channel settings.
2. In Uptime Kuma, add a Discord notification.
3. Paste the webhook URL.
4. Customize the bot display name and prefix message.
5. Test and save.

5.26 Configure Slack notifications

1. Create a Slack incoming webhook or Slack app.
2. In Uptime Kuma, add a Slack notification.
3. Paste the webhook URL.
4. Choose the channel and customize the message format.
5. Test and save.

5.27 Configure Telegram notifications

1. Create a bot via BotFather and get the bot token.
2. Get your chat ID (message the bot, then check via the API).
3. In Uptime Kuma, add a Telegram notification.
4. Paste bot token and chat ID.
5. Test and save.

5.28 Configure email (SMTP) notifications

1. In Uptime Kuma, add an SMTP notification.
2. Enter SMTP host, port, username, password.
3. Set from/to addresses.
4. Enable TLS/STARTTLS as needed.
5. Test and save.

5.29 Configure PagerDuty notifications

1. In PagerDuty, create a service and get the integration key.
2. In Uptime Kuma, add a PagerDuty notification.
3. Paste the integration key.
4. Test and save. Down events trigger PagerDuty incidents.

5.30 Configure webhook notifications

1. Add a Webhook notification.
2. Enter the target URL.
3. Choose content type (JSON or form-encoded).
4. Optionally add custom headers as JSON (Additional Headers is not a valid JSON if malformed).
5. Test and save.

This is the generic escape hatch for integrating with any system that accepts HTTP webhooks.

5.31 Set up a proxy for outbound monitoring

1. Settings → Proxies → Add Proxy.
2. Protocol: HTTP, HTTPS, SOCKS4, or SOCKS5.
3. Enter host, port, and optional auth.
4. Test and save.
5. In each monitor, select the proxy under Advanced → Proxy.

5.32 Use badges in your README

Embed live status badges in your GitHub README, wiki, or any Markdown file:

![Status](https://your-kuma/api/badge/1/status)
![Uptime](https://your-kuma/api/badge/1/uptime/720)
![Ping](https://your-kuma/api/badge/1/ping/24)

Available badge endpoints

Duration format

:duration accepts hours (24h), minutes (60m), or days (7d).

5.33 Export and import monitors

1. Settings → Backup → Export. A JSON file is downloaded containing all monitors, notifications, proxies, and status pages.
2. To import: Settings → Backup → Import. Select the JSON file.
3. Choose whether to overwrite existing monitors or merge.

5.34 Set up Cloudflare Tunnel

1. Create a Cloudflare Tunnel in your Cloudflare dashboard and get the token.
2. Set UPTIME_KUMA_CLOUDFLARED_TOKEN in your environment or pass --cloudflared-token.
3. Uptime Kuma automatically starts the tunnel on boot.
4. Alternatively, manage tunnels from the UI: Settings → Cloudflare Tunnels (accessible via Socket.IO handler).

5.35 Enable Prometheus metrics

Uptime Kuma exposes a /metrics endpoint in Prometheus format (via prom-client + prometheus-api-metrics). The endpoint is protected by basic auth using the first user's credentials.

Add to your prometheus.yml:

scrape_configs:
  - job_name: 'uptime-kuma'
    basic_auth:
      username: '<admin-username>'
      password: '<admin-password>'
    static_configs:
      - targets: ['your-kuma:3001']

5.36 Monitor with upside-down mode

For services that should be down (e.g., a decommissioned endpoint that must stay offline):

1. Add the appropriate monitor type.
2. Enable Upside Down Mode.
3. The monitor reports up when the target is unreachable and down when it responds.

5.37 Monitor certificate expiry

1. Add an HTTP(s) or TLS Certificate monitor.
2. Enable Certificate Expiry Notification.
3. Set the notification threshold (e.g., 30 days before expiry).
4. Attach a notification channel.

The monitor displays full certificate chain details: subject, issuer, serial, valid-from, valid-to, days remaining, and fingerprint.

5.38 Monitor domain expiry (RDAP/WHOIS)

HTTP monitors can track domain registration expiry via RDAP. The monitor displays days until domain expiration and can trigger notifications. Limitations:

• Only supported on HTTP(s) monitor types (domain_expiry_unsupported_monitor_type for others).
• The domain must have a valid RDAP endpoint (domain_expiry_unsupported_unsupported_tld_no_rdap_endpoint if the TLD lacks one).
• ICANN TLDs may produce domain_expiry_unsupported_is_icann.

5.39 Use the manual monitor

1. Add a Manual monitor.
2. Toggle status manually from the dashboard.
3. Useful for tracking things that cannot be auto-checked (e.g., "office printer status" or "vendor SLA compliance").

5.40 Monitor RabbitMQ

1. Add a RabbitMQ monitor.
2. Enter the management API nodes as JSON: ["http://rabbitmq:15672"].
3. Enter username and password.
4. Uptime Kuma queries the management API health check.
5. If all nodes fail: All X nodes failed because....

Invalid node JSON produces Invalid RabbitMQ Nodes. Empty list produces No RabbitMQ nodes configured.

6. Troubleshooting

6.1 Error: Your Node.js version: X is not supported

Cause. Node.js is below version 18, or in the 20.0.x through 20.3.x range which has known bugs. Solution. Upgrade to Node.js >= 20.4.0. Reinstall Uptime Kuma with npm run setup afterwards. Prevention. Pin Node.js via NVM and follow the LTS track.

6.2 Error: Knex: Timeout acquiring a connection

Cause. The database connection pool is saturated — usually MariaDB/MySQL under heavy load (issues #7260, #6486). Solution. Increase UPTIME_KUMA_DB_POOL_MAX_CONNECTIONS (default 10, capped at 100). Check for long-running queries. Restart Uptime Kuma. Prevention. Monitor your database server separately. Consider using a connection pooler.

6.3 Error: user not found, have you installed?

Cause. You ran npm run remove-2fa or npm run reset-password before completing first-time setup. Solution. Run Uptime Kuma normally, finish the setup wizard, then rerun the script. Prevention. Only use these scripts on a running, initialized install.

6.4 Error: Password is too weak, please use a stronger password.

Cause. Password failed the strength check during setup or reset. Solution. Use at least 12 characters with mixed case, digits, and symbols. Prevention. Use a password manager.

6.5 Error: Invalid db-config.json, it must be an object

Cause. ./data/db-config.json is malformed (manual edit, partial write, disk corruption). Solution. Delete db-config.json, restart. The setup wizard re-runs. Prevention. Never edit db-config.json by hand; use environment variables.

6.6 Error: Invalid db-config.json, type must be a string

Cause. The type field is missing or not a string in db-config.json. Solution. Restore from backup or delete the file so setup re-runs. Prevention. Back up ./data/ before upgrades.

6.7 Error: Unknown Database type:

Cause. UPTIME_KUMA_DB_TYPE set to an unsupported value. Solution. Use one of: sqlite, mariadb, mysql, mssql, postgres, embedded-mariadb.

6.8 Error: Both UPTIME_KUMA_DB_PASSWORD and UPTIME_KUMA_DB_PASSWORD_FILE are set

Cause. You set both the direct env var and the _FILE Docker secret variant. Solution. Pick one. Prefer _FILE for Docker Swarm / Kubernetes secrets.

6.9 Error: docker host not found

Cause. Docker Container monitor references a host that no longer exists or was never configured. Solution. Re-add the Docker host under Settings → Docker Hosts. For Unix sockets, mount /var/run/docker.sock into the container.

6.10 Error: Connection to Docker daemon timed out.

Cause. The Docker daemon did not respond within 30 seconds. Solution. Check that Docker is running. For TCP connections, verify firewall rules and TLS configuration.

6.11 Error: Invalid Docker response, is it Docker really a daemon?

Cause. The endpoint responds but is not the Docker API (maybe Portainer, Swarm UI, or a random HTTP service). Solution. Point the Docker host at the real Docker socket or API endpoint.

6.12 Error: Accepted status codes are not all strings

Cause. A bulk import or API call passed numeric status codes instead of strings. Solution. Quote all codes: "200" or "200-299" instead of bare 200.

6.13 Error: Invalid period.

Cause. A chart or badge request used an invalid period parameter. Solution. Use documented values: 1h, 24h, 7d, 30d, 1y.

6.14 Error: You do not own this monitor.

Cause. Monitor ownership mismatch in multi-session scenarios. Solution. Log in as the monitor owner.

6.15 Error: Permission denied.

Cause. An unauthenticated Socket.IO request tried a privileged action. Solution. Log in and re-issue the request.

6.16 Error: Remote Browser not found

Cause. A Real Browser monitor references a remote Chromium endpoint that was deleted. Solution. Re-add or remove the remote browser under Settings → Remote Browsers.

6.17 Error: proxy not found

Cause. A monitor references a proxy that was deleted. Solution. Re-assign a proxy under monitor edit, or set Proxy to "None".

6.18 Error: Invalid ping value. Must be between 0 and X ms.

Cause. A Push monitor received a ping value outside the allowed range. Solution. Normalize pings to integers within the allowed range (0 to the configured maximum).

6.19 Error: Dead loop occurred in parseCertificateInfo

Cause. A pathological certificate chain caused the parser to loop. Solution. Check the target site with openssl s_client -connect host:443 -showcerts to confirm chain sanity. Report the cert to the maintainers if it is valid but unparseable.

6.20 Web UI shows a spinner forever (never loads)

Cause. WebSocket handshake is blocked (reverse proxy missing Upgrade headers), or the WebSocket origin check is failing. Solution. Configure your reverse proxy to forward Upgrade and Connection: upgrade headers. If you are on a non-standard origin for development, set UPTIME_KUMA_WS_ORIGIN_CHECK=bypass (do not use in production).

6.21 Monitor shows up when TLS is actually broken

Cause. Some monitors report up on successful TCP even when TLS fails (issue #7265). This affects older 2.x builds. Solution. Update to the latest 2.x image.

6.22 Cannot host under a subdirectory (e.g., /uptimekuma)

Cause. Limited subpath support — the frontend assumes it runs at root. Solution. Host on a subdomain (kuma.example.com) instead of a subpath. Issue #7279 tracks this limitation.

6.23 Error: Chromium not found

Cause. Real Browser monitor cannot find a Chromium executable. Solution. Either configure a remote browser endpoint under Settings → Remote Browsers, or set UPTIME_KUMA_ALLOW_ALL_CHROME_EXEC=1 and ensure Chrome/Chromium is installed on the host.

6.24 Error: The token is invalid due to password change or old token

Cause. Your JWT session token was invalidated because the admin password was changed, or the token expired. Solution. Log in again. This is expected behavior after a password change.

6.25 Ping monitor fails with small packet sizes

Cause. Ping fails if you choose a packet size below 16 bytes (issue #3574). Solution. Use a packet size of 16 bytes or larger.

6.26 Notification timeout freezes the monitor

Cause. A slow notification provider blocks the heartbeat cycle (issue #4058). Solution. Switch to async-friendly notification channels (Webhook, Ntfy, Gotify) instead of synchronous providers. Or reduce the notification timeout if the provider supports it.

6.27 MQTT monitor does not accept mqtts:// URLs

Cause. The MQTT monitor parser rejects mqtts:// protocol URLs (issue #7286). Solution. Use mqtt:// with the TLS port, or configure a proxy.

6.28 DB migration fails on convert-float-precision

Cause. The database migration 2026-01-10-0000-convert-float-precision.js fails due to an interrupted previous migration attempt (issue #6920). Solution. Check if SET_MIGRATE_AGGREGATE_TABLE_TO_TRUE environment variable helps. If the migration was interrupted, the error Aggregate table migration is already in progress may appear. Restore from backup and retry.

6.29 Error: Incorrect current password

Cause. The password you entered when changing your password does not match. Solution. Enter the correct current password. If forgotten, use npm run reset-password from the host.

6.30 Error: Invalid timezone:

Cause. An invalid timezone string was provided. Solution. Use a valid IANA timezone (e.g., America/New_York, Europe/London, Asia/Tokyo).

6.31 Error: slug is not found

Cause. A status page operation references a slug that does not exist. Solution. Verify the status page slug in your URL or API call.

6.32 Error: Only allowed PNG logo.

Cause. You tried to upload a non-PNG file as a status page logo. Solution. Convert your logo to PNG format before uploading.

6.33 Error: Notification type is not supported

Cause. The notification configuration references a provider type that is not registered. Solution. Re-create the notification using a valid provider from the dropdown.

6.34 Error: Invalid url protocol, only http and https are allowed.

Cause. A Real Browser monitor was given a URL with a non-HTTP protocol. Solution. Use http:// or https:// URLs only for Real Browser monitors.

6.35 Error: Monitor not found or not active.

Cause. A push heartbeat was sent for a monitor that does not exist or is paused. Solution. Verify the push token and ensure the monitor is active.

6.36 Error: Unknown Monitor Type

Cause. A monitor has a type that is not registered in the system. This can happen after downgrading from a newer version. Solution. Edit the monitor and set a valid type, or delete and re-create it.

6.37 Error: Steam API Key not found

Cause. A Steam Game Server monitor requires a Steam API key that is not configured. Solution. Add your Steam API key in the monitor settings.

6.38 Error: Interval cannot be less than X seconds

Cause. The heartbeat interval or retry interval is below the minimum (20 seconds for heartbeat). Solution. Increase the interval to at least the minimum.

6.39 Rate limiting: Too frequently, try again later.

Cause. You exceeded a rate limit. Solution. Wait and retry. Rate limits:

6.40 Error: Invalid JSON in database query

Cause. A monitor's JSON configuration field (headers, conditions, accepted status codes, etc.) contains invalid JSON. Solution. Validate the JSON syntax. Common issues: trailing commas, unquoted keys, single quotes instead of double quotes.

7. FAQ

Q: What ports does Uptime Kuma use? Only 3001/tcp by default. Override with UPTIME_KUMA_PORT, the PORT env var, or --port.

Q: Where is my data stored? ./data/ inside the working directory (Node.js) or /app/data/ inside the container. SQLite lives at ./data/kuma.db; MariaDB/MySQL data is on the external database server.

Q: What is the minimum heartbeat interval? 20 seconds. Shorter intervals would overload both Uptime Kuma and the monitoring target.

Q: What is the maximum heartbeat interval? Defined by MAX_INTERVAL_SECOND in the source. For most monitor types there is a generous upper bound. Push monitors have a feature request for 30+ day intervals (issue #7264).

Q: Can I monitor more than 1000 services? Yes, but switch the database to MariaDB or MySQL, raise UPTIME_KUMA_DB_POOL_MAX_CONNECTIONS, and give the host enough RAM. Each monitor is a small timer + crontab entry.

Q: Does Uptime Kuma support multi-tenant / teams? Not officially. Uptime Kuma is designed as a single-admin tool. Use reverse-proxy auth if you need to share view-only access.

Q: Is there a REST API to create monitors? A public REST API is tracked under feature request #118. Today, read-only badges and push endpoints are exposed as HTTP. Most CRUD operations happen over the Socket.IO channel (not documented as a public API).

Q: How do I back up my data? Stop Uptime Kuma, copy ./data/ somewhere safe, start again. For MariaDB/MySQL use mysqldump. Automatic periodic backups are on the roadmap (issue #477).

Q: How do I update Uptime Kuma? Docker: docker pull louislam/uptime-kuma:2 && docker compose down && docker compose up -d. Node.js: git pull && npm run setup && pm2 restart uptime-kuma. Always back up ./data/ first.

Q: Can I use my own TLS certificate? Yes. Set UPTIME_KUMA_SSL_KEY and UPTIME_KUMA_SSL_CERT. Both must be set to enable HTTPS — partial config runs as HTTP. Optionally add UPTIME_KUMA_SSL_KEY_PASSPHRASE for encrypted keys.

Q: Does it work behind Cloudflare? Yes. It also supports Cloudflared tunnels: provide UPTIME_KUMA_CLOUDFLARED_TOKEN to start a tunnel automatically on boot.

Q: Can Uptime Kuma monitor itself? The container includes a HEALTHCHECK (Go binary at extra/healthcheck) and a Prometheus /metrics endpoint. For true external monitoring, use a second Uptime Kuma instance or a different monitoring service.

Q: How do I change the data directory? Set DATA_DIR (e.g., DATA_DIR=/var/kuma/) or pass --data-dir. The path must end with /.

Q: Does Uptime Kuma send my data anywhere? No telemetry. Notifications go only to the endpoints you configure. Version checks hit GitHub (disable via TEST_CHECK_VERSION=0).

Q: Why is a monitor still showing "up" when my site is down? Check the monitor type matches the failure you care about. A TCP monitor stays green if the port accepts a connection even when the application returns HTTP 500. Use an HTTP monitor with Accepted Status Codes for full-stack checks.

Q: Can I export my monitors? Yes. Settings → Backup → Export. A JSON file is produced. Re-import via the same page.

Q: What happens to history when I delete a monitor? It is permanently deleted. There is no soft-delete. Export the data first if you need to keep it.

Q: Does Chinese / non-ASCII input work everywhere? Yes. Uptime Kuma is fully Unicode-aware in names, descriptions, and notifications.

Q: How many notification providers are supported? 93 notification providers ship with version 2.2.1. See the full catalog in the Notification Providers section below.

Q: Can I send test notifications? Yes. Every notification channel has a Test button in the setup dialog. It sends a sample alert using the current configuration.

Q: Can I apply a notification to all monitors at once? Yes. When creating or editing a notification channel, check Apply on all existing monitors.

Q: What databases can I monitor? MySQL/MariaDB, PostgreSQL, MongoDB, Microsoft SQL Server, Oracle DB, and Redis.

Q: Can I monitor a Kafka cluster? Yes, via the Kafka Producer monitor type. Configure broker addresses and optional SASL authentication as valid JSON.

Q: What game servers can I monitor? Any server supported by the GameDig library (Minecraft, Valheim, Counter-Strike, ARK, Team Fortress 2, and hundreds more). For Steam servers specifically, use the Steam Game Server type.

Q: Can I monitor a RADIUS server? Yes, via the built-in RADIUS monitor type. Enter the RADIUS server address, shared secret, and test credentials.

Q: How do I set up 2FA? Settings → Security → Enable 2FA. Scan the TOTP QR code with any TOTP app. Each token is single-use within its 30-second window.

Q: How do I reset 2FA if I lose my authenticator? From the server host: npm run remove-2fa. It prompts for the username.

Q: How do I reset the admin password? From the server host: npm run reset-password. It prompts for the username and new password.

Q: Can I disable authentication entirely? Yes, under Settings → Security → Disable Auth. Not recommended for internet-facing instances.

Q: What is the entryPage setting? Under Settings → General, you choose whether the root URL (/) redirects to the dashboard or a specific status page.

Q: Does Uptime Kuma support OIDC / OAuth login? Yes. Configure under Settings → Security → OIDC / OAuth with client ID, secret, discovery URL, and scopes.

Q: Can I embed Uptime Kuma in an iframe? By default, X-Frame-Options: SAMEORIGIN prevents cross-origin embedding. Set UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN to allow it.

Q: What is the .well-known/change-password endpoint? Uptime Kuma serves this endpoint per the W3C specification, allowing password managers to find the password change page.

Q: Can I use structured JSON logging? Yes. Set UPTIME_KUMA_LOG_FORMAT=json for JSON-formatted log output.

Appendices

Appendix A: Notification provider catalog (93 providers)

All notification providers ship under server/notification-providers/ and are registered at startup.

Appendix B: Helper npm scripts

Appendix C: Health check

The Docker image includes extra/healthcheck (a Go binary) and extra/healthcheck.js (a Node.js fallback). Docker runs the health check every 60 seconds with:

• Timeout: 30 seconds
• Retries: 5
• Start period: 180 seconds

The health check makes an HTTP(S) request to the local server, respecting the same SSL configuration environment variables.

Appendix D: Prometheus metrics

GET /metrics returns Prometheus-format metrics (exposed via prom-client + prometheus-api-metrics). This includes default Node.js runtime metrics (memory, event loop, GC) plus per-monitor heartbeat data.

The endpoint requires basic auth using the admin credentials.

Appendix E: External resources

• Official wiki: https://github.com/louislam/uptime-kuma/wiki
• Milestones and roadmap: https://github.com/louislam/uptime-kuma/milestones
• Subreddit: https://www.reddit.com/r/UptimeKuma/
• Translations (Weblate): https://weblate.kuma.pet/