louislam/uptime-kuma · error · Error

Hostname is required

Error message

Hostname is required

What it means

Thrown at the top of NTPMonitorType.check when monitor.hostname is falsy. The NTP monitor needs a target host to resolve and query over UDP/123, so a missing hostname is a configuration defect, not a runtime/network problem.

Source

Thrown at server/monitor-types/ntp.js:21

const dayjs = require("dayjs");
const dgram = require("dgram");
const dns = require("dns");

/**
 * NTP Monitor Type
 * Monitors NTP servers for availability, time accuracy, and quality metrics
 */
class NTPMonitorType extends MonitorType {
    name = "ntp";

    /**
     * @inheritdoc
     */
    async check(monitor, heartbeat, _server) {
        const startTime = dayjs().valueOf();

        if (!monitor.hostname) {
            throw new Error("Hostname is required");
        }

        const port = monitor.port || 123;
        const timeout = (monitor.timeout || 10) * 1000;

        const ntpResult = await this.queryNTP(monitor.hostname, port, timeout);

        heartbeat.ping = dayjs().valueOf() - startTime;

        const { stratum, offset, rootDispersion, refid, roundTripDelay } = ntpResult;

        heartbeat.msg = `Stratum: ${stratum}, RefID: ${refid}, Offset: ${offset.toFixed(3)}ms, Delay: ${roundTripDelay.toFixed(3)}ms, Dispersion: ${rootDispersion.toFixed(3)}ms`;

        if (stratum === 16) {
            throw new Error("NTP server is unsynchronized (stratum 16)");
        }

        const stratumThreshold = monitor.ntp_stratum_threshold || 5;

View on GitHub (pinned to 6b5ea01557)

Solutions

1. Set monitor.hostname to the NTP server hostname or IP (e.g. 'pool.ntp.org').
2. Add UI/API-level validation requiring hostname before persistence for the 'ntp' type.
3. If importing monitors, validate each row has a non-empty hostname.

Example fix

// before: monitor.hostname = ''
// after:  monitor.hostname = 'pool.ntp.org'

function requireNtpHostname(monitor) {
  if (!monitor.hostname || typeof monitor.hostname !== 'string' || !monitor.hostname.trim())
    throw new Error('NTP monitor requires a hostname');
}

function hasNtpHostname(m) { return typeof m?.hostname === 'string' && m.hostname.trim().length > 0; }

When it happens

Trigger: check() invoked with a monitor object whose hostname is undefined, null, '' or 0. Occurs when a monitor was created without the hostname field, the field was cleared via the API, or a provisioning script omitted it.

Common situations: Provisioning/import script that did not set hostname; frontend allowed saving with empty hostname due to a bug; monitor cloned without setting the new target.

Related errors

• Stratum ${stratum} meets or exceeds threshold ${stratumThres
• Root dispersion ${rootDispersion.toFixed(3)}ms exceeds thres
• Interval cannot be less than ${MIN_INTERVAL_SECOND} seconds
• Retry interval cannot be less than ${MIN_INTERVAL_SECOND} se
• Response max length cannot be less than 0

AI-assisted analysis of louislam/uptime-kuma@6b5ea01557 (2026-08-12). Data as JSON: /api/errors/8ae2123697d8b75d. Report an issue: GitHub.