tobi/qmd · error · Error

Refusing to initialize a local index in $HOME. The global in

Error message

Refusing to initialize a local index in $HOME. The global index is automatically created; run `qmd collection add <path>` for the global index, or run `qmd init` inside a project folder.

What it means

Thrown by initLocalIndex (qmd init) when the current working directory is the user's home directory. QMD refuses project-local .qmd indexes in $HOME because the global index already lives there conceptually and a home-local index would shadow every project.

Source

Thrown at src/cli/qmd.ts:443

function formatBytes(bytes: number): string {
  if (bytes < 1024) return `${bytes} B`;
  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
}

function sameDirectory(a: string, b: string): boolean {
  try {
    return realpathSync(a) === realpathSync(b);
  } catch {
    return pathResolve(a) === pathResolve(b);
  }
}

function initLocalIndex(): void {
  const cwd = getPwd();
  if (sameDirectory(cwd, homedir())) {
    throw new Error("Refusing to initialize a local index in $HOME. The global index is automatically created; run `qmd collection add <path>` for the global index, or run `qmd init` inside a project folder.");
  }

  const qmdDir = pathJoin(cwd, ".qmd");
  const ymlPath = pathJoin(qmdDir, "index.yml");
  const yamlPath = pathJoin(qmdDir, "index.yaml");
  const configPath = existsSync(yamlPath) ? yamlPath : ymlPath;
  const dbPath = pathJoin(qmdDir, "index.sqlite");

  mkdirSync(qmdDir, { recursive: true });
  setConfigSource({ configPath });
  storeDbPathOverride = dbPath;
  closeDb();

  if (!existsSync(configPath)) {
    saveConfig({
      collections: {},
      models: resolveModels(),
    });

View on GitHub (pinned to dbfd0b4736)

Solutions

1. cd into the project folder and run `qmd init` there
2. For a global (cross-project) index, skip init and run `qmd collection add <path> --name <n>` instead

Example fix

# before
cd ~ && qmd init
# after
cd ~/projects/myrepo && qmd init

import { homedir } from 'node:os';
if (process.cwd() === homedir()) throw new Error('refusing qmd init in $HOME; cd to a project first');

When it happens

Trigger: Running `qmd init` from $HOME (e.g. right after SSH login or opening a terminal at ~).

Common situations: New users running qmd init immediately at the shell prompt; shell configured to start in $HOME; cd'ing home before initializing.

Related errors

• Collection not found: ${collection}\n${hint}
• No indexed documents found.\nIndex a collection with 'qmd co
• Collection name is required. Collections must be defined in
• ${name} must be a positive integer
• --chunk-strategy must be "auto" or "regex" (got "${s}")

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