tobi/qmd · error · Error

expand: query must include text.

Error message

expand: query must include text.

What it means

Thrown by the CLI query-document parser when a standalone expand: line has no text after the colon. The expand query needs the natural-language description to feed LLM query expansion.

Source

Thrown at src/cli/qmd.ts:2745

    number: idx + 1,
  })).filter(line => line.trimmed.length > 0);

  if (rawLines.length === 0) return null;

  const prefixRe = /^(lex|vec|hyde):\s*/i;
  const expandRe = /^expand:\s*/i;
  const intentRe = /^intent:\s*/i;
  const typed: ExpandedQuery[] = [];
  let intent: string | undefined;

  for (const line of rawLines) {
    if (expandRe.test(line.trimmed)) {
      if (rawLines.length > 1) {
        throw new Error(`Line ${line.number} starts with expand:, but query documents cannot mix expand with typed lines. Submit a single expand query instead.`);
      }
      const text = line.trimmed.replace(expandRe, '').trim();
      if (!text) {
        throw new Error('expand: query must include text.');
      }
      return null; // treat as standalone expand query
    }

    // Parse intent: lines
    if (intentRe.test(line.trimmed)) {
      if (intent !== undefined) {
        throw new Error(`Line ${line.number}: only one intent: line is allowed per query document.`);
      }
      const text = line.trimmed.replace(intentRe, '').trim();
      if (!text) {
        throw new Error(`Line ${line.number}: intent: must include text.`);
      }
      intent = text;
      continue;
    }

    const match = line.trimmed.match(prefixRe);

View on GitHub (pinned to dbfd0b4736)

Solutions

1. Add the topic text: 'expand: how to set up vector search'
2. Ensure script variables are set before interpolating into the query

Example fix

# before
printf 'expand:' | qmd query
# after
printf 'expand: how to set up vector search' | qmd query

if (/^\s*expand:\s*$/im.test(doc)) throw new Error('expand: line has no text');

const expandHasText = (doc: string) => !/^\s*expand:\s*$/im.test(doc);

When it happens

Trigger: Piping 'expand:' or 'expand: ' as the query document to `qmd query`.

Common situations: Empty variable expansion in scripts (`echo "expand: $Q"` with Q unset); placeholder text never replaced.

Related errors

• Line ${line.number} starts with expand:, but query documents
• Line ${line.number}: only one intent: line is allowed per qu
• Line ${line.number}: intent: must include text.
• Line ${line.number} (${type}:) must include text.
• Line ${line.number} (${type}:) contains a newline. Keep each

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