{"record":{"id":"52ab444b3fc73dfd","repo":"bmad-code-org/BMAD-METHOD","slug":"source-for-module-modulename-is-not-available","errorCode":null,"errorMessage":"Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.","messagePattern":"Source for module '(.+?)' is not available\\. It will be retained but cannot be updated without its source files\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"tools/installer/modules/official-modules.js","lineNumber":271,"sourceCode":"   * @param {Object} options.logger - Logger instance for output\n   */\n  async install(moduleName, bmadDir, fileTrackingCallback = null, options = {}) {\n    // Check if this module has a plugin resolution (custom marketplace install)\n    const { CustomModuleManager } = require('./custom-module-manager');\n    const customMgr = new CustomModuleManager();\n    const resolved = customMgr.getResolution(moduleName);\n    if (resolved) {\n      return this.installFromResolution(resolved, bmadDir, fileTrackingCallback, options);\n    }\n\n    const sourcePath = await this.findModuleSource(moduleName, {\n      silent: options.silent,\n      channelOptions: options.channelOptions,\n    });\n    const targetPath = path.join(bmadDir, moduleName);\n\n    if (!sourcePath) {\n      throw new Error(\n        `Source for module '${moduleName}' is not available. It will be retained but cannot be updated without its source files.`,\n      );\n    }\n\n    if (await fs.pathExists(targetPath)) {\n      await fs.remove(targetPath);\n    }\n\n    // Marketplace-plugin registry modules keep their installable skills outside\n    // the directory that holds module.yaml (sourcePath points at the -setup\n    // skill's assets/), so they cannot be installed by copying sourcePath. Copy\n    // the resolved skill directories instead, matching how custom marketplace\n    // installs lay out a module. Everything else (manifest, version info) flows\n    // through the standard external-module path below.\n    const moduleInfo = await this.externalModuleManager.getModuleByCode(moduleName);\n    if (moduleInfo && moduleInfo.marketplacePlugin) {\n      const pluginResolution = this.externalModuleManager.getPluginResolution(moduleName);\n      // Fail loud: copying sourcePath here would install only the -setup skill's","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/bmad-code-org/BMAD-METHOD/blob/b70486b9bdcb0a404d329e2a763b57964e7f1360/tools/installer/modules/official-modules.js#L253-L289","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the installer to re-clone the module from its source.","If installed from a local path, ensure the original source directory still exists.","Clear the cache for this module and re-install: rm -rf ~/.bmad/cache/external-modules/<code>.","If the module was removed from the registry, remove it from your project's module list."],"exampleFix":"// before — cache deleted, source gone\nawait officialModules.install('my-module', bmadDir);\n\n// after — re-establish source first\n// Clear stale cache\nawait fs.remove(path.join(os.homedir(), '.bmad', 'cache', 'external-modules', 'my-module'));\n// Re-install (re-clones from source)\nawait officialModules.install('my-module', bmadDir);","handlingStrategy":"fallback","validationCode":"// Pre-check: verify source is available before attempting install\nconst sourcePath = await officialModules.findModuleSource(moduleName, { silent: true });\nif (!sourcePath) {\n  // Try clearing stale cache and re-resolving\n  const cacheDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules', moduleName);\n  if (fs.existsSync(cacheDir)) {\n    await fs.remove(cacheDir);\n  }\n  // Re-check\n  const retry = await officialModules.findModuleSource(moduleName, { silent: true });\n  if (!retry) {\n    throw new Error(`Source for '${moduleName}' is unavailable. Check network and registry.`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await officialModules.install(moduleName, bmadDir, fileTrackingCallback, options);\n} catch (e) {\n  if (e.message.includes('Source for module') && e.message.includes('is not available')) {\n    // Clear cache and retry\n    const cacheDir = path.join(os.homedir(), '.bmad', 'cache');\n    await fs.remove(cacheDir);\n    console.log('Cache cleared. Retrying install...');\n    await officialModules.install(moduleName, bmadDir, fileTrackingCallback, options);\n    return;\n  }\n  throw e;\n}","preventionTips":["Do not manually delete ~/.bmad/cache without re-running the installer.","For local-source modules, keep the original source directory in place.","Re-run the full installer if the cache is lost to re-clone all module sources.","Record the module source URL in your project setup documentation for recovery."],"tags":["filesystem","cache","source-resolution","install","external-modules"],"backgroundTag":null,"analyzedSha":"b70486b9bdcb0a404d329e2a763b57964e7f1360","analyzedAt":"2026-08-13T01:21:12.247Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}