What causes "Unknown MQTT Check Type" in louislam/uptime-kuma?

Set mqttCheckType to 'keyword' or 'json-query' (or clear it, which defaults to 'keyword')

louislam/uptime-kuma · error · Error

Unknown MQTT Check Type

Error message

Unknown MQTT Check Type

What it means

Thrown by the MQTT monitor when mqttCheckType is not 'keyword', not 'json-query', and no condition group is defined (or it has no children). The code falls through every branch to the else. Note: null/empty mqttCheckType is normalised to 'keyword' earlier, so this only fires for a genuinely unrecognised non-empty value.

Source

Thrown at server/monitor-types/mqtt.js:48

            websocketPath: monitor.mqttWebsocketPath,
        });

        if (monitor.mqttCheckType == null || monitor.mqttCheckType === "") {
            monitor.mqttCheckType = "keyword";
        }

        // Check if conditions are defined
        const conditions = monitor.conditions ? ConditionExpressionGroup.fromMonitor(monitor) : null;
        const hasConditions = conditions && conditions.children && conditions.children.length > 0;

        if (hasConditions) {
            await this.checkConditions(monitor, heartbeat, messageTopic, receivedMessage, conditions);
        } else if (monitor.mqttCheckType === "keyword") {
            this.checkKeyword(monitor, heartbeat, messageTopic, receivedMessage);
        } else if (monitor.mqttCheckType === "json-query") {
            await this.checkJsonQuery(monitor, heartbeat, receivedMessage);
        } else {
            throw new Error("Unknown MQTT Check Type");
        }
    }

    /**
     * Check using keyword matching
     * @param {object} monitor Monitor object
     * @param {object} heartbeat Heartbeat object
     * @param {string} messageTopic Received MQTT topic
     * @param {string} receivedMessage Received MQTT message
     * @returns {void}
     * @throws {Error} If keyword is not found in message
     */
    checkKeyword(monitor, heartbeat, messageTopic, receivedMessage) {
        if (receivedMessage != null && receivedMessage.includes(monitor.mqttSuccessMessage)) {
            heartbeat.msg = `Topic: ${messageTopic}; Message: ${receivedMessage}`;
            heartbeat.status = UP;
        } else {
            throw new Error(`Message Mismatch - Topic: ${monitor.mqttTopic}; Message: ${receivedMessage}`);

View on GitHub (pinned to 6b5ea01557)

Solutions

Set mqttCheckType to 'keyword' or 'json-query' (or clear it, which defaults to 'keyword')
If you intended condition-based checks, define at least one condition so hasConditions is true
Upgrade Uptime Kuma if a newer version supports the check type you need
Inspect the monitor record in the DB to confirm the mqttCheckType value is not corrupted

Example fix

// before: unknown value
monitor.mqttCheckType = "regex"; // unsupported -> throws
// after: supported value
monitor.mqttCheckType = "keyword";

Defensive patterns

Strategy: type-guard

Validate before calling

const validTypes = ["keyword", "json-query"];
if (monitor.mqttCheckType == null || monitor.mqttCheckType === "") {
    monitor.mqttCheckType = "keyword";
} else if (!validTypes.includes(monitor.mqttCheckType) && !hasConditions) {
    throw new Error("Unknown MQTT Check Type: " + monitor.mqttCheckType);
}

Type guard

/** @param {string} t */
function isKnownMqttCheckType(t) {
    return t === "keyword" || t === "json-query";
}

Try / catch

// Validate the enum value early so the error is actionable
if (!hasConditions && !isKnownMqttCheckType(monitor.mqttCheckType)) {
    throw new Error("Unknown MQTT Check Type: " + monitor.mqttCheckType);
}

Prevention

Constrain mqttCheckType to the supported enum at the UI/API layer
If you rely on conditions, ensure at least one child condition exists
Upgrade Uptime Kuma to gain new check types rather than hand-editing the DB

When it happens

Trigger: monitor.mqttCheckType is a non-empty string that is neither 'keyword' nor 'json-query', AND monitor.conditions is absent or produces a ConditionExpressionGroup with zero children.

Common situations: mqttCheckType was set to a value from a newer Uptime Kuma version this build doesn't recognise, the DB column was manually edited to an invalid value, or a migration wrote an unexpected enum.

Related errors

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