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 when a query document contains only an intent: line and no actual search lines. intent: is metadata that sharpens ranking of lex:/vec:/hyde: searches, so it cannot constitute a query by itself.

Source

Thrown at src/cli/qmd.ts:2787

      }
      if (/\r|\n/.test(text)) {
        throw new Error(`Line ${line.number} (${type}:) contains a newline. Keep each query on a single line.`);
      }
      typed.push({ type, query: text, line: line.number });
      continue;
    }

    if (rawLines.length === 1) {
      // Single plain line -> implicit expand
      return null;
    }

    throw new Error(`Line ${line.number} is missing a lex:/vec:/hyde:/intent: prefix. Each line in a query document must start with one.`);
  }

  // intent: alone is not a valid query — must have at least one search
  if (intent && typed.length === 0) {
    throw new Error('intent: cannot appear alone. Add at least one lex:, vec:, or hyde: line.');
  }

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

function search(query: string, opts: OutputOptions): void {
  const db = getDb();

  // Validate collection filter (supports multiple -c flags)
  // Use default collections if none specified
  const collectionNames = resolveCollectionFilter(opts.collection, true);

  // Use large limit for --all, otherwise fetch more than needed and let outputResults filter
  const fetchLimit = opts.all ? 100000 : Math.max(50, opts.limit * 2);
  const results = searchFTS(db, query, fetchLimit, collectionSearchFilter(collectionNames));

  // Add context to results
  const resultsWithContext = results.map(r => ({

View on GitHub (pinned to dbfd0b4736)

Solutions

  1. Add at least one lex:, vec:, or hyde: line alongside intent:
  2. Drop intent: and use a plain single-line query instead

Example fix

# before
intent: find setup instructions
# after
intent: find setup instructions
lex:setup instructions
vec:how to set up the project
Defensive patterns

Strategy: validation

Validate before calling

function hasSearchLine(raw: string): boolean {
  return raw.split(/\r?\n/).some((l) => /^(lex:|vec:|hyde:)/.test(l));
}

Type guard

null

Try / catch

null

Prevention

When it happens

Trigger: Calling `qmd query` with a document whose only typed line is intent: (e.g. `intent: find setup instructions` with no lex:/vec:/hyde: lines).

Common situations: Assuming intent: is itself a search mode; refactoring a query file and deleting the search lines while keeping intent:.

Related errors

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