tobi/qmd · error · Error

--timeout must be a non-negative number of minutes (0 = no l

Error message

--timeout must be a non-negative number of minutes (0 = no limit)

What it means

Thrown by parseEmbedTimeoutOption when `qmd embed --timeout` receives a value that is not a finite non-negative number of minutes. The timeout caps the whole embed session; 0 means no limit, negative or non-numeric values are rejected.

Source

Thrown at src/cli/qmd.ts:2109

    throw new Error(`${name} must be a positive integer`);
  }
  return parsed;
}

function parseChunkStrategy(value: unknown): ChunkStrategy | undefined {
  if (value === undefined) return undefined;
  const s = String(value);
  if (s === "auto" || s === "regex") return s;
  throw new Error(`--chunk-strategy must be "auto" or "regex" (got "${s}")`);
}

// --timeout for `qmd embed`: a cap on the whole embed session, in minutes. Returns
// the value in milliseconds, or undefined to use the default. 0 disables the cap.
function parseEmbedTimeoutOption(value: unknown): number | undefined {
  if (value === undefined) return undefined;
  const minutes = Number(value);
  if (!Number.isFinite(minutes) || minutes < 0) {
    throw new Error(`--timeout must be a non-negative number of minutes (0 = no limit)`);
  }
  return minutes * 60 * 1000;
}

function ensureModelsConfiguredForCli(): { embed: string; generate: string; rerank: string } {
  try {
    const config = loadConfig();
    const models = resolveModels(config.models);
    const current = config.models ?? {};
    if (current.embed !== models.embed || current.generate !== models.generate || current.rerank !== models.rerank) {
      saveConfig({
        ...config,
        models: {
          ...current,
          embed: models.embed,
          generate: models.generate,
          rerank: models.rerank,
        },

View on GitHub (pinned to dbfd0b4736)

Solutions

1. Pass minutes as a non-negative number: `qmd embed --timeout 30`
2. Use 0 to disable the cap: `qmd embed --timeout 0`
3. Default shell variables in scripts: `--timeout "${TIMEOUT:-10}"`

Example fix

# before
qmd embed --timeout 3600
# after
qmd embed --timeout 60

const m = Number(v);
if (!Number.isFinite(m) || m < 0) throw new RangeError('--timeout must be >= 0 minutes');

const isValidTimeout = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0;

When it happens

Trigger: Running `qmd embed --timeout -5`, `--timeout abc`, or passing an empty-string variable from a shell script; passing seconds (e.g. 3600) which yields an absurdly large but technically valid value.

Common situations: Script variables unset/empty; unit confusion (assuming seconds or milliseconds); typo'd numbers.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• ${name} must be a positive integer
• --chunk-strategy must be "auto" or "regex" (got "${s}")
• Collection not found: ${collection}\n${hint}
• No indexed documents found.\nIndex a collection with 'qmd co
• Refusing to initialize a local index in $HOME. The global in

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