louislam/uptime-kuma · error · Error

Screenshot delay must be a non-negative number

Error message

Screenshot delay must be a non-negative number

What it means

Thrown by Monitor.validate() for type "real-browser" when screenshot_delay is set (not undefined/null) and Number(screenshot_delay) is NaN or negative. The delay is the milliseconds the headless browser waits after navigation before capturing the screenshot.

Source

Thrown at server/model/monitor.js:1755

                    pingGlobalTimeout < this.ping_per_request_timeout ||
                    pingGlobalTimeout < PING_GLOBAL_TIMEOUT_MIN ||
                    pingGlobalTimeout > PING_GLOBAL_TIMEOUT_MAX
                ) {
                    throw new Error(
                        `Timeout must be between ${PING_GLOBAL_TIMEOUT_MIN} and ${PING_GLOBAL_TIMEOUT_MAX} seconds (default: ${PING_GLOBAL_TIMEOUT_DEFAULT})`
                    );
                }

                this.timeout = pingGlobalTimeout;
            }
        }

        if (this.type === "real-browser") {
            // screenshot_delay validation
            if (this.screenshot_delay !== undefined && this.screenshot_delay !== null) {
                const delay = Number(this.screenshot_delay);
                if (isNaN(delay) || delay < 0) {
                    throw new Error("Screenshot delay must be a non-negative number");
                }

                // Must not exceed 0.8 * timeout (page.goto timeout is interval * 1000 * 0.8)
                const maxDelayFromTimeout = this.interval * 1000 * 0.8;
                if (delay >= maxDelayFromTimeout) {
                    throw new Error(`Screenshot delay must be less than ${maxDelayFromTimeout}ms (0.8 × interval)`);
                }

                // Must not exceed 0.5 * interval to prevent blocking next check
                const maxDelayFromInterval = this.interval * 1000 * 0.5;
                if (delay >= maxDelayFromInterval) {
                    throw new Error(`Screenshot delay must be less than ${maxDelayFromInterval}ms (0.5 × interval)`);
                }
            }
        }

        if (this.type === "mongodb" && this.databaseQuery) {
            // Validate that databaseQuery is valid JSON

View on GitHub (pinned to 6b5ea01557)

Solutions

1. Set screenshot_delay to a non-negative number of milliseconds, or omit it.
2. Strip any non-numeric characters and use a dot decimal separator before submission.
3. If you need zero delay, use 0 explicitly or leave the field blank.

Example fix

// before
{ type: "real-browser", screenshot_delay: "500ms" }
// after
{ type: "real-browser", screenshot_delay: 500 }

function validScreenshotDelay(v) {
  if (v == null) return true;
  const n = Number(v);
  return !isNaN(n) && n >= 0;
}

function isScreenshotDelay(v) {
  if (v == null) return true;
  const n = Number(v);
  return typeof n === "number" && !isNaN(n) && n >= 0;
}

try {
  await bean.validate();
} catch (e) {
  if (/Screenshot delay must be a non-negative/.test(e.message)) return badRequest("screenshot_delay must be >= 0 ms");
  throw e;
}

When it happens

Trigger: Save a real-browser monitor with screenshot_delay="abc" (NaN), =-100, or an empty string (coerces to 0, which is allowed). The guard runs only when the field is present.

Common situations: User enters the delay as a fraction with a comma locale ("0,5" -> NaN). Negative values from a misconfigured form default. Passing the field as a string with units ("500ms").

Related errors

• Screenshot delay must be less than ${maxDelayFromTimeout}ms
• Screenshot delay must be less than ${maxDelayFromInterval}ms
• Service Name is required.
• Invalid service name. Please use the internal Service Name (
• Invalid PM2 process name.

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