{"record":{"id":"3468b5c39b2ef80e","repo":"abhigyanpatwari/GitNexus","slug":"storage-requirement-not-met-state-is-inspection-state","errorCode":null,"errorMessage":"Storage requirement not met: state is \"${inspection.state}\"","messagePattern":"Storage requirement not met: state is \"(.+?)\"","errorType":"exception","errorClass":"StorageRequirementError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/storage/storage-resolver.ts","lineNumber":613,"sourceCode":"  }\n  return inspectStoragePath(storagePath, repoPath);\n};\n\n/**\n * Inspect a registry-selected slot without allowing an environment override to\n * redirect the entry to another repository's storage.\n */\nexport const inspectRegisteredStorage = async (entry: {\n  path: string;\n  storagePath: string;\n}): Promise<StorageInspection> => inspectStoragePath(entry.storagePath, entry.path);\n\nconst requireInspectedStoragePath = (\n  inspection: StorageInspection,\n  requirements: StorageRequirements,\n): string => {\n  if (!requirements.allowedStates.includes(inspection.state)) {\n    throw new StorageRequirementError(inspection, requirements);\n  }\n  // `foreign` is only adoptable for this checkout's own `.gitnexus`. An\n  // external slot that names another repository stays rejected even when the\n  // caller opted into `foreign` (analyze/index --force).\n  if (\n    inspection.state === 'foreign' &&\n    !isRepositoryLocalStoragePath(inspection.repoPath, inspection.storagePath)\n  ) {\n    throw new StorageRequirementError(inspection, {\n      ...requirements,\n      allowedStates: requirements.allowedStates.filter((state) => state !== 'foreign'),\n    });\n  }\n  if (requirements.requireCodeIndexDB && !inspection.hasCodeIndexDB) {\n    throw new StorageRequirementError(inspection, requirements);\n  }\n  return inspection.storagePath;\n};","sourceCodeStart":595,"sourceCodeEnd":631,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/storage/storage-resolver.ts#L595-L631","documentation":"This is a StorageRequirementError thrown by requireInspectedStoragePath in storage-resolver.ts when the inspected storage directory's state (e.g. 'missing', 'foreign', 'owned', 'unowned') is not among the states the caller declared as acceptable. GitNexus refuses to proceed against a storage slot whose ownership/integrity state does not satisfy the operation's requirements, to protect an index that belongs to another checkout or is unusable. The message embeds the actual state via inspection.state.","triggerScenarios":"Calling requireStoragePath / analyze / index against a repo whose .gitnexus storage inspection returns a state not listed in requirements.allowedStates — e.g. storage belongs to a foreign repository, or an 'owned' slot is required but the directory is 'missing' or 'empty'.","commonSituations":"Running analyze in a repo whose .gitnexus was created by a different checkout; GITNEXUS_STORAGE_PATH pointing at a slot named for another repo; a deleted or never-created storage directory when the command requires an existing index.","solutions":["Read the 'state' value in the error message and reconcile it with what the command needs — usually by re-running analyze to create/claim the storage directory.","Remove or fix the stale .gitnexus directory (or GITNEXUS_STORAGE_PATH) so the inspection yields an allowed state, then re-run.","If the foreign-slot case is intentional, use the documented --force option of analyze/index, which opts into adoptable foreign slots.","Point GITNEXUS_STORAGE_PATH at the correct slot that belongs to this checkout instead of another repository's."],"exampleFix":"// before\nGITNEXUS_STORAGE_PATH=/shared/index-cache npx gitnexus analyze\n// after (point at this repo's own slot, or let it default to <repo>/.gitnexus)\nunset GITNEXUS_STORAGE_PATH && npx gitnexus analyze","handlingStrategy":"try-catch","validationCode":"import { inspectStoragePath } from './storage-resolver.js';\nconst inspection = await inspectStoragePath(storagePath);\nif (!['missing','empty','unowned','owned'].includes(inspection.state)) {\n  throw new Error(`Storage not usable: state=${inspection.state}`);\n}","typeGuard":"const isAllowedState = (s: string): s is StorageState =>\n  ['missing','empty','unowned','owned','foreign'].includes(s);","tryCatchPattern":"try {\n  await requireStoragePath(repoPath, { allowedStates: ['owned'] });\n} catch (err) {\n  if (err instanceof StorageRequirementError) {\n    console.error(`Storage state is ${err.inspection.state}; re-run analyze or fix GITNEXUS_STORAGE_PATH`);\n  } else throw err;\n}","preventionTips":["Inspect storage state with the inspection API before running index-dependent commands.","Avoid sharing GITNEXUS_STORAGE_PATH across checkouts of different repos.","Run analyze before any command that requires an existing index.","Use --force only when you understand the foreign-slot implications."],"tags":["storage","index","config"],"backgroundTag":"invalid-state-transition","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-09-15T23:29:44.066Z","contentChangedAt":"2026-09-15T23:29:44.066Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}