Fission-AI/OpenSpec · error · StoreError

store_register_root_unhealthy

store_register_root_unhealthy

Error message

Store register requires an existing healthy OpenSpec root. ${problems}${emptyCloneHint}

What it means

Thrown by registerExistingStore when inspectOpenSpecRoot reports the candidate folder is not a healthy OpenSpec root. The message aggregates the inspector's diagnostics and, when the folder is a Git repo with no commits, appends an empty-clone hint — the most common cause.

Solutions

1. Address each diagnostic listed in the message (missing dirs, incomplete root)
2. If it is an empty clone, fetch/checkout the default branch so the committed OpenSpec root appears
3. Use 'openspec store setup' to initialize a fresh root instead

When it happens

Trigger: Thrown at src/core/store/operations.ts:778 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Fission-AI/OpenSpec@6926ccb18a (2026-08-25). Data as JSON: /api/errors/e41d738d38832654. Report an issue: GitHub.

Appendix: source

Thrown at src/core/store/operations.ts:778

        fix: 'Pass an existing store directory.',
      }
    );
  }

  assertNotConfigOnlyPointerRoot(storeRoot);
  const openspecRoot = await inspectOpenSpecRoot(storeRoot);
  if (!openspecRoot.healthy) {
    const problems =
      openspecRoot.diagnostics.map((diagnostic) => diagnostic.message).join(' ') ||
      'The OpenSpec root is missing or incomplete.';
    const isEmptyCloneSuspect =
      (await isGitRepositoryAtRoot(storeRoot)) &&
      (await gitHasCommits(storeRoot)) === false;
    const emptyCloneHint = isEmptyCloneSuspect
      ? ' This folder is a Git repository with no commits — if it is a clone, the origin store needs an initial commit before the clone has any files.'
      : '';

    throw new StoreError(
      `Store register requires an existing healthy OpenSpec root. ${problems}${emptyCloneHint}`,
      'store_register_root_unhealthy',
      {
        target: 'openspec.root',
        fix: isEmptyCloneSuspect
          ? 'If this is a store clone: commit and push the origin store, pull it into this clone, then rerun register.'
          : 'Run openspec store setup for a new store, or point register at a checkout whose openspec/ files are present.',
      }
    );
  }

  const metadata = await readStoreMetadataForOperation(storeRoot);
  const explicitId = input.id !== undefined ? validateStoreId(input.id) : undefined;

  if (metadata && explicitId !== undefined && metadata.id !== explicitId) {
    // The fix must account for whether the metadata id is already registered,
    // so following it never lands on the already-registered error.
    const currentRegistry = await readStoreRegistryState();

View on GitHub (pinned to 6926ccb18a)