{"record":{"id":"fedd8f222e33c010","repo":"tobi/qmd","slug":"refusing-to-initialize-a-local-index-in-home-the","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/cli/qmd.ts","lineNumber":443,"sourceCode":"function formatBytes(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;\n  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;\n  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;\n}\n\nfunction sameDirectory(a: string, b: string): boolean {\n  try {\n    return realpathSync(a) === realpathSync(b);\n  } catch {\n    return pathResolve(a) === pathResolve(b);\n  }\n}\n\nfunction initLocalIndex(): void {\n  const cwd = getPwd();\n  if (sameDirectory(cwd, homedir())) {\n    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.\");\n  }\n\n  const qmdDir = pathJoin(cwd, \".qmd\");\n  const ymlPath = pathJoin(qmdDir, \"index.yml\");\n  const yamlPath = pathJoin(qmdDir, \"index.yaml\");\n  const configPath = existsSync(yamlPath) ? yamlPath : ymlPath;\n  const dbPath = pathJoin(qmdDir, \"index.sqlite\");\n\n  mkdirSync(qmdDir, { recursive: true });\n  setConfigSource({ configPath });\n  storeDbPathOverride = dbPath;\n  closeDb();\n\n  if (!existsSync(configPath)) {\n    saveConfig({\n      collections: {},\n      models: resolveModels(),\n    });","sourceCodeStart":425,"sourceCodeEnd":461,"githubUrl":"https://github.com/tobi/qmd/blob/dbfd0b4736aeaf761d1a16ca8e424f071df8feb9/src/cli/qmd.ts#L425-L461","documentation":"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.","triggerScenarios":"Running `qmd init` from $HOME (e.g. right after SSH login or opening a terminal at ~).","commonSituations":"New users running qmd init immediately at the shell prompt; shell configured to start in $HOME; cd'ing home before initializing.","solutions":["cd into the project folder and run `qmd init` there","For a global (cross-project) index, skip init and run `qmd collection add <path> --name <n>` instead"],"exampleFix":"# before\ncd ~ && qmd init\n# after\ncd ~/projects/myrepo && qmd init","handlingStrategy":"validation","validationCode":"import { homedir } from 'node:os';\nif (process.cwd() === homedir()) throw new Error('refusing qmd init in $HOME; cd to a project first');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always cd into the project directory before qmd init","Use qmd collection add for global-scope indexing"],"tags":["cli","init","filesystem"],"backgroundTag":"invalid-working-directory","analyzedSha":"dbfd0b4736aeaf761d1a16ca8e424f071df8feb9","analyzedAt":"2026-08-28T18:07:46.628Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}