What causes "Invalid query: ${query} – see https://bit.ly/2s3ChXG" in squidfunk/mkdocs-material?

Enter a query with at least one term before any wildcard, e.g. 'inst*' instead of '*'

Invalid query: ${query} – see https://bit.ly/2s3ChXG

Error message

Invalid query: ${query} – see https://bit.ly/2s3ChXG

What it means

The Material for MkDocs built-in search integration's web worker calls index.search(query) inside a try/catch. If the query makes lunr throw (e.g. a lone wildcard or unbalanced syntax), the handler logs 'Invalid query: <query> – see https://bit.ly/2s3ChXG' plus the error to the console and returns an empty result set instead of crashing the worker. It is a console warning, not an exception surfaced to the user.

Source

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

    case SearchMessageType.SETUP:
      await setupSearchLanguages(message.data.config)
      index = new Search(message.data)
      return {
        type: SearchMessageType.READY
      }

    /* Search query message */
    case SearchMessageType.QUERY:
      const query = message.data
      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 */

View on GitHub (pinned to e2136532f4)

Solutions

Enter a query with at least one term before any wildcard, e.g. 'inst*' instead of '*'
Remove or balance quote characters and special lunr operators in the query
Note that results are intentionally empty here — fix the query rather than the site configuration
If legitimate queries keep failing, check the lunr version bundled with the theme and update Material for MkDocs
If a custom search pipeline/extension is installed, verify it handles edge-case tokens

Example fix

// before (browser search input)
search: "*"
// after
search: "mkdocs*"

Defensive patterns

Strategy: fallback

Validate before calling

// in the search UI before posting to the worker
function isValidQuery(query: string): boolean {
  const trimmed = query.trim()
  return trimmed.length > 0 && !/^\*+$/.test(trimmed)
}
if (!isValidQuery(query)) return // skip search for wildcard-only queries

Type guard

function isSearchable(query: string): boolean {
  return query.trim().length > 0 && query.trim() !== "*"
}

Try / catch

// the worker already falls back gracefully; mirror it on the caller side
worker.addEventListener("message", (ev) => {
  if (ev.data.type === SearchMessageType.RESULT && ev.data.data.items.length === 0) {
    console.warn(`Empty results — query may be invalid: ${lastQuery}`)
  }
})

Prevention

Require at least one term before a wildcard in the search box
Strip or escape unbalanced quotes and lunr special characters from user input
Show a hint in the UI when a search returns empty items
Keep Material for MkDocs updated so bundled lunr fixes are included
Treat this as a console warning only — the worker already recovers with empty results

When it happens

Trigger: A user types a query that lunr cannot parse — commonly a bare '*' wildcard with no term (e.g. searching just '*'), unbalanced quotes, or other lunr query syntax it rejects in the pipeline function.

Common situations: Users pasting '*' or '?:' style patterns into the documentation search box; queries with stray quotes or special lunr field syntax; localized input where a lone wildcard is used as a 'show everything' shortcut.

Related errors

Invalid message type

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