tobi/qmd · error · Error

search() requires either 'query' or 'queries'

Error message

search() requires either 'query' or 'queries'

What it means

The store's search method requires either query (single string) or queries (multiple strings); calling it with neither leaves nothing to search, so it throws immediately. This is a client-side argument validation error, not a search failure.

Source

Thrown at src/index.ts:400

  // Create a per-store LlamaCpp instance — lazy-loads models on first use,
  // auto-unloads after 5 min inactivity to free VRAM.
  const llm = new LlamaCpp({
    embedModel: config?.models?.embed,
    generateModel: config?.models?.generate,
    rerankModel: config?.models?.rerank,
    inactivityTimeoutMs: 5 * 60 * 1000,
    disposeModelsOnInactivity: true,
  });
  internal.llm = llm;

  const store: QMDStore = {
    internal,
    dbPath: internal.dbPath,

    // Search
    search: async (opts) => {
      if (!opts.query && !opts.queries) {
        throw new Error("search() requires either 'query' or 'queries'");
      }
      // Normalize collection/collections
      const collections = [
        ...(opts.collection ? [opts.collection] : []),
        ...(opts.collections ?? []),
      ];
      const skipRerank = opts.rerank === false;

      if (opts.queries) {
        // Pre-expanded queries — use structuredSearch
        return structuredSearch(internal, opts.queries, {
          collections: collections.length > 0 ? collections : undefined,
          limit: opts.limit,
          minScore: opts.minScore,
          explain: opts.explain,
          intent: opts.intent,
          candidateLimit: opts.candidateLimit,
          skipRerank,

View on GitHub (pinned to dbfd0b4736)

Solutions

1. Default the query or bail early when it's absent
2. Use the plural queries array for multi-query search
3. Validate/trim user input before calling search

Example fix

// before
const results = await store.search({ collection });
// after
if (!query?.trim()) return [];
const results = await store.search({ query, collection });

const q = opts.query?.trim();
if (!q && !opts.queries?.length) return []; // or throw your own error

const hasSearchTerm = (o: SearchOptions): boolean =>
  Boolean(o.query?.trim() || o.queries?.some(q => q?.trim()));

When it happens

Trigger: Calling store.search({collection: 'notes'}) with no query; passing an empty string '' as query (falsy); building opts dynamically where query ends up undefined.

Common situations: Optional search inputs from CLI args or HTTP handlers where the query param is missing; empty-string query from user input; refactors renaming query to q or text.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• dbPath is required
• Provide either configPath or config, not both
• ${location} (${search.type}): queries must be single-line. R
• Line ${line.number} is missing a lex:/vec:/hyde:/intent: pre
• intent: cannot appear alone. Add at least one lex:, vec:, or

AI-assisted analysis of tobi/qmd@dbfd0b4736 (2026-08-28). Data as JSON: /api/errors/ffef85606ddd5ee9. Report an issue: GitHub.