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

Module '${moduleName}' not found in any source location

Error message

Module '${moduleName}' not found in any source location

What it means

Thrown by OfficialModules.update when findModuleSource(moduleName) returns null. findModuleSource checks the built-in 'core' and 'bmm' modules, then external official modules (via externalModuleManager, honoring channelOptions), then custom modules already cloned to cache; null means none recognized the code. Update refuses to proceed without a source to sync from.

Source

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

      // lines show the same string we just wrote to disk (custom git-backed
      // installs show the cloned ref or 'main').
      versionInfo: {
        version: resolved.cloneRef || (hasGitClone ? 'main' : resolved.version || ''),
      },
    };
  }

  /**
   * Update an existing module
   * @param {string} moduleName - Name of the module to update
   * @param {string} bmadDir - Target bmad directory
   */
  async update(moduleName, bmadDir) {
    const sourcePath = await this.findModuleSource(moduleName);
    const targetPath = path.join(bmadDir, moduleName);

    if (!sourcePath) {
      throw new Error(`Module '${moduleName}' not found in any source location`);
    }

    if (!(await fs.pathExists(targetPath))) {
      throw new Error(`Module '${moduleName}' is not installed`);
    }

    await this.syncModule(sourcePath, targetPath);

    return {
      success: true,
      module: moduleName,
      path: targetPath,
    };
  }

  /**
   * Remove a module
   * @param {string} moduleName - Name of the module to remove

View on GitHub (pinned to b70486b9bd)

Solutions

1. Confirm the module code matches the installed directory name under _bmad/ and the entry in _bmad/manifest.json.
2. For custom-source modules, re-run install with the original --custom-source <url> to repopulate the clone cache, then retry update.
3. Run from the repo root so findModuleSource's getProjectRoot resolves built-in sources correctly.
4. Verify the external module is still listed in the registry for your channel (--all-stable / --pin can change visibility).

Example fix

// before: update fails because custom-source cache was cleared
//   await modules.update('myplugin', bmadDir);  // -> Module 'myplugin' not found
//
// after: re-establish the source first
//   await modules.installFromResolution(
//     customMgr.resolveSource('https://github.com/me/myplugin', ...),
//     bmadDir,
//   );
//   await modules.update('myplugin', bmadDir);

const sourcePath = await modules.findModuleSource(moduleName, { channelOptions });
if (!sourcePath) {
  console.error(`No source for ${moduleName}; reinstall via --custom-source or check the channel.`);
  return;
}
await modules.update(moduleName, bmadDir);

try {
  await modules.update(moduleName, bmadDir);
} catch (e) {
  if (/not found in any source location/.test(e.message)) {
    // re-establish source then retry, or skip
    await modules.installFromResolution(customMgr.resolveSource(url, opts), bmadDir);
    await modules.update(moduleName, bmadDir);
  } else { throw e; }
}

When it happens

Trigger: Calling installer.update('somemodule', bmadDir) where 'somemodule' is neither 'core', 'bmm', a registered external official module for the configured channel, nor a previously-cloned custom module. Also when channelOptions hide an external module that would otherwise resolve.

Common situations: A custom-source module whose clone cache was cleared; module code misspelled vs. the directory name in _bmad/; the external module registry changed or network/channel misconfiguration hides the module; running update from a different cwd so getProjectRoot resolves source paths incorrectly.

Related errors

• Module '${moduleName}' is not installed
• version is not available when nothing is installed
• ${label} does not exist: ${dirPath}
• ${label} is not a directory: ${dirPath}
• ${label} is not readable: ${dirPath}

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