tobi/qmd · error · Error

intent: cannot appear alone. Add at least one lex:, vec:, or

Error message

intent: cannot appear alone. Add at least one lex:, vec:, or hyde: line.

What it means

Thrown after parsing when a bench fixture query document contains an intent: line but zero typed search lines. intent: is metadata that sharpens ranking of lex:/vec:/hyde: searches and cannot stand alone.

Source

Thrown at src/bench/bench.ts:90

    if (match) {
      const type = match[1]!.toLowerCase() as "lex" | "vec" | "hyde";
      const text = line.trimmed.slice(match[0].length).trim();
      if (!text) {
        throw new Error(`Line ${line.number} (${type}:) must include text.`);
      }
      searches.push({ type, query: text, line: line.number });
      continue;
    }

    if (lines.length === 1) {
      return undefined;
    }

    throw new Error(`Line ${line.number} is missing a lex:/vec:/hyde:/intent: prefix.`);
  }

  if (intent && searches.length === 0) {
    throw new Error("intent: cannot appear alone. Add at least one lex:, vec:, or hyde: line.");
  }

  return searches.length > 0 ? { searches, intent } : undefined;
}

function uniqueFiles(files: string[], limit: number): string[] {
  const seen = new Set<string>();
  const out: string[] = [];
  for (const file of files) {
    if (seen.has(file)) continue;
    seen.add(file);
    out.push(file);
    if (out.length >= limit) break;
  }
  return out;
}

const BACKENDS: Backend[] = [

View on GitHub (pinned to dbfd0b4736)

Solutions

1. Add at least one lex:, vec:, or hyde: line to the same query document
2. Use an expand: query (single line) if you want LLM query expansion instead

Example fix

// before
"intent: find setup docs"
// after
"intent: find setup docs\nlex: setup documentation"

const typed = (doc.match(/^\s*(lex|vec|hyde):/gim) || []).length;
const intent = /^\s*intent:/im.test(doc);
if (intent && typed === 0) throw new Error('intent: requires at least one typed search line');

const intentHasSearch = (doc: string) => !/^\s*intent:/im.test(doc) || /^\s*(lex|vec|hyde):/im.test(doc);

When it happens

Trigger: A fixture query document consisting solely of 'intent: find docs' with no lex:/vec:/hyde: lines.

Common situations: Writing an intent-only query expecting expansion; deleting the typed lines but keeping the intent annotation.

Related errors

• Line ${line.number}: only one intent: line is allowed per be
• Line ${line.number}: intent: must include text.
• Line ${line.number} (${type}:) must include text.
• Line ${line.number} is missing a lex:/vec:/hyde:/intent: pre
• Invalid fixture: missing 'queries' array

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