louislam/uptime-kuma · error · Error

Additional Headers is not a valid JSON

Error message

Additional Headers is not a valid JSON

What it means

Thrown by the SMTP provider when JSON.parse fails on the user-supplied notification.smtpAdditionalHeaders string. The field is expected to hold a JSON object of extra MIME/SMTP headers (e.g. {"X-Custom":"value"}); any malformed JSON raises SyntaxError which is caught and re-thrown with this message before nodemailer is constructed.

Source

Thrown at server/notification-providers/smtp.js:66

        }

        // Should fix the issue in https://github.com/louislam/uptime-kuma/issues/26#issuecomment-896373904
        if (notification.smtpUsername || notification.smtpPassword) {
            config.auth = {
                user: notification.smtpUsername,
                pass: notification.smtpPassword,
            };
        }

        // Handle additional headers
        if (notification.smtpAdditionalHeaders) {
            try {
                config.headers = {
                    ...config.headers,
                    ...JSON.parse(notification.smtpAdditionalHeaders),
                };
            } catch (err) {
                throw new Error("Additional Headers is not a valid JSON");
            }
        }

        // default values in case the user does not want to template
        let subject = msg;
        let body = msg;
        let useHTMLBody = false;
        if (heartbeatJSON) {
            body = `${msg}\nTime (${heartbeatJSON["timezone"]}): ${heartbeatJSON["localDateTime"]}`;
        }
        // subject and body are templated
        if ((monitorJSON && heartbeatJSON) || msg.endsWith("Testing")) {
            // cannot end with whitespace as this often raises spam scores
            const customSubject = notification.customSubject?.trim() || "";
            const customBody = notification.customBody?.trim() || "";
            if (customSubject !== "") {
                subject = await this.renderTemplate(customSubject, msg, monitorJSON, heartbeatJSON);
            }

View on GitHub (pinned to 6b5ea01557)

Solutions

1. Validate the value in a JSON linter (jsonlint.com) before saving.
2. Use double quotes for both keys and string values and wrap the whole thing in {}.
3. Remove trailing commas and comments — strict JSON allows neither.
4. If you need multiple headers, express them as one object: {"X-A":"1","X-B":"2"}.

Example fix

// before (in notification config)
smtpAdditionalHeaders: X-Priority: 1, X-MSMail-Priority: High
// after
smtpAdditionalHeaders: {"X-Priority":"1","X-MSMail-Priority":"High"}

// Validate additional headers BEFORE building the transporter
function parseAdditionalHeaders(raw) {
    if (!raw) return {};
    let parsed;
    try {
        parsed = JSON.parse(raw);
    } catch (e) {
        throw new Error(`Additional Headers is not valid JSON: ${e.message}`);
    }
    if (typeof parsed !== "object" || Array.isArray(parsed) || parsed === null) {
        throw new Error("Additional Headers must be a JSON object");
    }
    return parsed;
}
config.headers = { ...config.headers, ...parseAdditionalHeaders(notification.smtpAdditionalHeaders) };

/** True when raw parses to a flat object of header strings. */
function isValidHeadersObject(raw) {
    try {
        const o = JSON.parse(raw);
        return o && typeof o === "object" && !Array.isArray(o) &&
            Object.values(o).every((v) => typeof v === "string");
    } catch { return false; }
}

try {
    config.headers = { ...config.headers, ...JSON.parse(notification.smtpAdditionalHeaders) };
} catch (err) {
    throw new Error(`Additional Headers is not a valid JSON: ${err.message}`);
}

When it happens

Trigger: Entering key: value pairs without braces/quotes, trailing commas, single-quoted keys, pasting from a YAML/curl -H list, or HTML entity encoding from a rich-text editor.

Common situations: User copies headers from a curl -H invocation, uses Python-dict syntax instead of JSON, or the UI field is filled with newlines that break strict JSON parsing.

Related errors

• Additional Headers is not a valid JSON
• Kafka Producer Brokers must be valid JSON: ${e.message}
• Kafka Producer SASL Options must be valid JSON: ${e.message}
• RabbitMQ Nodes must be valid JSON: ${e.message}
• Conditions must be valid JSON: ${e.message}

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