What causes "Invalid message type" in squidfunk/mkdocs-material?

Check the type field of the message you postMessage; it must exactly match a type the worker's switch handles.

squidfunk/mkdocs-material · error · TypeError

Invalid message type

Error message

Invalid message type

What it means

The search worker's message handler processes messages posted to the Web Worker via postMessage. When a message arrives whose type does not match any known case in the handler's switch statement, it throws a TypeError("Invalid message type"). This guards the worker's protocol: only defined message types (e.g. search/query setup) are accepted.

Source

Thrown at src/templates/assets/javascripts/integrations/search/worker/main/index.ts:178

      try {
        return {
          type: SearchMessageType.RESULT,
          data: index.search(query)
        }

      /* Return empty result in case of error */
      } catch (err) {
        console.warn(`Invalid query: ${query} – see https://bit.ly/2s3ChXG`)
        console.warn(err)
        return {
          type: SearchMessageType.RESULT,
          data: { items: [] }
        }
      }

    /* All other messages */
    default:
      throw new TypeError("Invalid message type")
  }
}

/* ----------------------------------------------------------------------------
 * Worker
 * ------------------------------------------------------------------------- */

/* Expose Lunr.js in global scope, or stemmers won't work */
self.lunr = lunr

/* Monkey-patch Lunr.js to mitigate https://t.ly/68TLq */
lunr.utils.warn = console.warn

/* Handle messages */
addEventListener("message", async ev => {
  postMessage(await handler(ev.data))
})

View on GitHub (pinned to e2136532f4)

Solutions

Check the type field of the message you postMessage; it must exactly match a type the worker's switch handles.
Regenerate/refresh the bundled search worker and integration scripts so host and worker use the same protocol version.
If you need custom messages, extend the worker's handler rather than reusing this one, or handle your messages before forwarding to the worker.

Example fix

// before
worker.postMessage({ type: "SEARCH", query })

// after
worker.postMessage({ type: "SEARCH_START", data: query })

Defensive patterns

Strategy: type-guard

Validate before calling

const KNOWN = ["SEARCH_START", "SEARCH_READY"] // types the worker handles
if (!KNOWN.includes(message.type)) {
  console.warn("Unknown worker message", message)
  return
}
worker.postMessage(message)

Type guard

type WorkerMessageType = "SEARCH_START" | "SEARCH_READY"
function isWorkerMessage(data: unknown): data is { type: WorkerMessageType; data?: unknown } {
  return typeof data === "object" && data !== null &&
    "type" in data && typeof (data as { type: unknown }).type === "string"
}

Try / catch

worker.onerror = (event) => {
  if (String(event.message).includes("Invalid message type")) {
    // log payload, fall back to non-worker search
  }
}

Prevention

Keep the host integration and worker scripts from the same Material version.
Centralize message type constants shared between page and worker.
Never post raw unvetted messages to the search worker from custom code.
Write a small test that round-trips each message type through the worker.

When it happens

Trigger: postMessage({ type: <unknown> }) sent to the search worker from a custom script or integration; a version mismatch where the host page sends a message type the bundled worker no longer understands; corrupted or hand-built message payloads.

Common situations: Custom worker scripts in overrides that fork the search integration; upgrading Material while keeping an old custom search integration (or vice versa); third-party plugins posting their own messages to the shared worker.

Related errors

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/06aee7bc8a3ba969. Report an issue: GitHub.