bmad-code-org/BMAD-METHOD · error · Error

Tag '${planEntry.pin}' not found in ${parsed.owner}/${parsed

Error message

Tag '${planEntry.pin}' not found in ${parsed.owner}/${parsed.repo}.

What it means

Thrown by cloneExternalModule() during pinned-channel validation when tagExists() confirms the requested --pin tag does not exist in the module's GitHub repository (owner/repo). The check runs before cloning to fail fast and avoid wasting time on a clone that would fail anyway.

Source

Thrown at tools/installer/modules/external-manager.js:346

      throw new Error(`Could not resolve stable tag for '${moduleCode}' (${error.message}). ${hint}`);
    }

    if (resolved.resolvedFallback && !silent) {
      if (resolved.reason === 'no-stable-tags') {
        await prompts.log.warn(`No stable releases found for ${moduleInfo.name}; installing from main.`);
      } else if (resolved.reason === 'not-a-github-url') {
        await prompts.log.warn(`Cannot determine stable tags for ${moduleInfo.name} (non-GitHub URL); installing from main.`);
      }
    }

    // Validate pin before we burn time cloning. Best-effort: skip on non-GitHub URLs.
    if (planEntry.channel === 'pinned') {
      const parsed = parseGitHubRepo(moduleInfo.url);
      if (parsed) {
        try {
          const exists = await tagExists(parsed.owner, parsed.repo, planEntry.pin);
          if (!exists) {
            throw new Error(`Tag '${planEntry.pin}' not found in ${parsed.owner}/${parsed.repo}.`);
          }
        } catch (error) {
          if (error.message?.includes('not found')) throw error;
          // Network hiccup on tag verification — let the clone attempt fail clearly.
        }
      }
    }

    // ─── Clone or update cache by resolved channel ────────────────────────
    const markerPath = path.join(moduleCacheDir, '.bmad-channel.json');
    const currentMarker = await readChannelMarker(markerPath);
    const needsChannelReset = currentMarker && currentMarker.channel !== resolved.channel;

    let needsDependencyInstall = false;
    let wasNewClone = false;

    if (needsChannelReset && (await fs.pathExists(moduleCacheDir))) {
      // Channel changed (e.g. user switched stable→next). Blow away and re-clone

View on GitHub (pinned to b70486b9bd)

Solutions

1. List available tags: visit the GitHub releases page or run 'git ls-remote --tags <repo-url>'.
2. Correct the tag name in the --pin flag.
3. If the tag exists but under a different format, match the exact string (e.g., 'v1.2.3' vs '1.2.3').
4. If you want the latest main branch instead, use --next=<moduleCode> instead of --pin.

Example fix

# before
npx bmad-method install --pin my-module=v2.0.0
# (tag 'v2.0.0' doesn't exist)

# after
# Check tags: git ls-remote --tags https://github.com/org/repo.git
npx bmad-method install --pin my-module=2.0.0

const { tagExists, parseGitHubRepo } = require('./channel-resolver');

// Pre-validate the pin tag exists
const moduleInfo = await extMgr.getModuleByCode(moduleCode);
const parsed = parseGitHubRepo(moduleInfo.url);
if (parsed) {
  const exists = await tagExists(parsed.owner, parsed.repo, requestedTag);
  if (!exists) {
    throw new Error(`Tag '${requestedTag}' not found in ${parsed.owner}/${parsed.repo}`);
  }
}

try {
  await extMgr.cloneExternalModule(moduleCode, { channelOptions: { pins: new Map([[moduleCode, tag]]) } });
} catch (e) {
  if (e.message.includes('not found in')) {
    console.error('The pinned tag does not exist. List tags with: git ls-remote --tags <repo-url>');
    // Fall back to --next
    await extMgr.cloneExternalModule(moduleCode, { channelOptions: { nextSet: new Set([moduleCode]) } });
    return;
  }
  throw e;
}

When it happens

Trigger: Installing with --pin <moduleCode>=<tag> where <tag> does not exist in the module's GitHub repo. The tagExists() call queries the GitHub API and returns false. Note: this check only runs when the module URL is a GitHub URL (parseGitHubRepo succeeds).

Common situations: Typo in the tag name; the tag was deleted or never created; the user confused a branch name with a tag name; the version number format is wrong (v1.0 vs 1.0.0).

Related errors

• Unsafe ref name: ${JSON.stringify(ref)}
• Could not resolve stable tag for '${moduleCode}' (${error.me
• Failed to clone external module '${moduleCode}' at ${resolve
• Module '${moduleCode}' was downloaded but its module definit
• Unexpected response from ${url}

AI-assisted analysis of bmad-code-org/BMAD-METHOD@b70486b9bd (2026-08-13). Data as JSON: /api/errors/fb502affb5534070. Report an issue: GitHub.