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

Source for module '${moduleName}' is not available. It will

Error message

Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.

What it means

Thrown by OfficialModules.install() when findModuleSource() returns null — no source path was found for the module in any location: not in core/bmm built-in paths, not in external module cache, and not in custom module cache or manifest. The module cannot be installed or updated without its source files.

Source

Thrown at tools/installer/modules/official-modules.js:271

   * @param {Object} options.logger - Logger instance for output
   */
  async install(moduleName, bmadDir, fileTrackingCallback = null, options = {}) {
    // Check if this module has a plugin resolution (custom marketplace install)
    const { CustomModuleManager } = require('./custom-module-manager');
    const customMgr = new CustomModuleManager();
    const resolved = customMgr.getResolution(moduleName);
    if (resolved) {
      return this.installFromResolution(resolved, bmadDir, fileTrackingCallback, options);
    }

    const sourcePath = await this.findModuleSource(moduleName, {
      silent: options.silent,
      channelOptions: options.channelOptions,
    });
    const targetPath = path.join(bmadDir, moduleName);

    if (!sourcePath) {
      throw new Error(
        `Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.`,
      );
    }

    if (await fs.pathExists(targetPath)) {
      await fs.remove(targetPath);
    }

    // Marketplace-plugin registry modules keep their installable skills outside
    // the directory that holds module.yaml (sourcePath points at the -setup
    // skill's assets/), so they cannot be installed by copying sourcePath. Copy
    // the resolved skill directories instead, matching how custom marketplace
    // installs lay out a module. Everything else (manifest, version info) flows
    // through the standard external-module path below.
    const moduleInfo = await this.externalModuleManager.getModuleByCode(moduleName);
    if (moduleInfo && moduleInfo.marketplacePlugin) {
      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);
      // Fail loud: copying sourcePath here would install only the -setup skill's

View on GitHub (pinned to b70486b9bd)

Solutions

1. Re-run the installer to re-clone the module from its source.
2. If installed from a local path, ensure the original source directory still exists.
3. Clear the cache for this module and re-install: rm -rf ~/.bmad/cache/external-modules/<code>.
4. If the module was removed from the registry, remove it from your project's module list.

Example fix

// before — cache deleted, source gone
await officialModules.install('my-module', bmadDir);

// after — re-establish source first
// Clear stale cache
await fs.remove(path.join(os.homedir(), '.bmad', 'cache', 'external-modules', 'my-module'));
// Re-install (re-clones from source)
await officialModules.install('my-module', bmadDir);

// Pre-check: verify source is available before attempting install
const sourcePath = await officialModules.findModuleSource(moduleName, { silent: true });
if (!sourcePath) {
  // Try clearing stale cache and re-resolving
  const cacheDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules', moduleName);
  if (fs.existsSync(cacheDir)) {
    await fs.remove(cacheDir);
  }
  // Re-check
  const retry = await officialModules.findModuleSource(moduleName, { silent: true });
  if (!retry) {
    throw new Error(`Source for '${moduleName}' is unavailable. Check network and registry.`);
  }
}

try {
  await officialModules.install(moduleName, bmadDir, fileTrackingCallback, options);
} catch (e) {
  if (e.message.includes('Source for module') && e.message.includes('is not available')) {
    // Clear cache and retry
    const cacheDir = path.join(os.homedir(), '.bmad', 'cache');
    await fs.remove(cacheDir);
    console.log('Cache cleared. Retrying install...');
    await officialModules.install(moduleName, bmadDir, fileTrackingCallback, options);
    return;
  }
  throw e;
}

When it happens

Trigger: Calling install() for a module whose cache was cleared, whose local source directory was deleted, or whose registry entry was removed. Also when a custom module was installed from a local path that no longer exists and no manifest localPath is recorded.

Common situations: The ~/.bmad/cache directory was manually deleted; the module was installed from a temporary local path that was cleaned up; the module's GitHub repo was deleted and no cache remains; network failure during both cache lookup and fresh clone.

Related errors

• Module '${moduleName}' is registered as a marketplace plugin
• ${label} does not exist: ${dirPath}
• ${label} is not a directory: ${dirPath}
• ${label} is not readable: ${dirPath}
• ${label} does not exist: ${filePath}

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