Could not retire capability '${update.id}': ${update.target}

Error message

Could not retire capability '${update.id}': ${update.target} resolves outside ${mainSpecsDir}. Remove the external file by hand, or replace the symlink and rerun.

What it means

Error "Could not retire capability '${update.id}': ${update.target} resolves outside ${mainSpecsDir}. Remove the external file by hand, or replace the symlink and rerun." thrown in Fission-AI/OpenSpec.

Source

Thrown at src/core/specs-apply.ts:825

    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { retired: false };
    throw new Error(
      `Could not retire capability '${update.id}': could not verify ${update.target} ` +
        `before deletion (${error instanceof Error ? error.message : String(error)}).`
    );
  }

  if (realSource !== undefined) {
    let inside: boolean;
    try {
      inside = await isInsideRealDir(realSource, mainSpecsDir);
    } catch (error) {
      throw new Error(
        `Could not retire capability '${update.id}': could not verify that ${update.target} ` +
          `is inside ${mainSpecsDir} (${error instanceof Error ? error.message : String(error)}).`
      );
    }
    if (!inside) {
      throw new Error(
        `Could not retire capability '${update.id}': ${update.target} resolves outside ` +
          `${mainSpecsDir}. Remove the external file by hand, or replace the symlink and rerun.`
      );
    }
  }

  let displacedPath: string | undefined;
  try {
    await options.beforeMutate?.();
    if (options.verifyDisplaced) {
      const displaced = `${update.target}.openspec-retire-${randomUUID()}`;
      displacedPath = displaced;
      await fs.rename(update.target, displaced);
      try {
        await options.verifyDisplaced(displaced);
        try {
          await fs.lstat(update.target);
          throw new Error(

View on GitHub (pinned to 6926ccb18a)

When it happens

Trigger: Thrown at src/core/specs-apply.ts:825 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/2fb97307255d4c78. Report an issue: GitHub.