{"record":{"id":"4c399de08cbda968","repo":"mastra-ai/mastra","slug":"could-not-find-a-plugin-entry-file-tried-entry","errorCode":null,"errorMessage":"Could not find a plugin entry file. Tried: ${ENTRY_CANDIDATES.join(', ')}","messagePattern":"Could not find a plugin entry file\\. Tried: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/plugins/install.ts","lineNumber":183,"sourceCode":"    if (!fs.existsSync(entryPath) || !fs.statSync(entryPath).isFile()) {\n      throw new Error(`Plugin entry file does not exist: ${explicitEntry}`);\n    }\n    return path.relative(root, entryPath);\n  }\n\n  const manifestPlugin = getSingleManifestPlugin(pluginDir);\n  if (manifestPlugin) {\n    return detectEntry(pluginDir, manifestPlugin.entry);\n  }\n\n  for (const candidate of ENTRY_CANDIDATES) {\n    const entryPath = path.join(pluginDir, candidate);\n    if (fs.existsSync(entryPath) && fs.statSync(entryPath).isFile()) {\n      return candidate;\n    }\n  }\n\n  throw new Error(`Could not find a plugin entry file. Tried: ${ENTRY_CANDIDATES.join(', ')}`);\n}\n\nfunction isInsideDirectory(targetPath: string, root: string): boolean {\n  return targetPath === root || targetPath.startsWith(root + path.sep);\n}\n\nasync function runPluginInstallCommand(\n  command: string,\n  args: string[],\n  execaOptions: typeof NON_INTERACTIVE_EXEC_OPTIONS & { cwd?: string },\n  options: PluginInstallExecutionOptions,\n): Promise<void> {\n  const child = execa(command, args, {\n    ...execaOptions,\n    stdout: options.onOutput ? 'pipe' : 'ignore',\n    stderr: options.onOutput ? 'pipe' : 'ignore',\n    cancelSignal: options.signal,\n  });","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/plugins/install.ts#L165-L201","documentation":"When no explicit entry is given, detectEntry probes a list of conventional entry candidates (ENTRY_CANDIDATES) inside the plugin directory. If none exists as a regular file, the SDK throws listing all tried candidates so the author knows what to create.","triggerScenarios":"Calling entry/detectEntry(pluginDir) with no explicitEntry, no single manifest plugin, and none of the ENTRY_CANDIDATES paths existing as files in pluginDir.","commonSituations":"Plugin directories missing an index.ts/mastra equivalent; entry lives in `src/` while only `dist/` output exists; empty or mis-created plugin folder; entry file named unconventionally (e.g. `plugin.ts`) without configuring `entry`.","solutions":["Create one of the conventional entry files listed in the error message (typically `index.ts` at the plugin root).","Set an explicit `entry` option pointing at your actual file, e.g. `entry: 'src/plugin.ts'`.","Verify you are pointing the installer at the plugin's source directory, not `dist/` or a parent folder.","Add a valid manifest declaring the plugin/entry if the convention differs."],"exampleFix":"// before: plugin dir contains only plugin.ts, no config\nmastra plugin install ./my-plugin\n\n// after: specify the entry\nmastra plugin install ./my-plugin --entry src/plugin.ts\n// or add index.ts at the plugin root","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nimport path from 'node:path';\nconst CANDIDATES = ['index.ts', 'src/index.ts', 'plugin.ts', 'src/plugin.ts'];\nexport function hasEntryCandidate(pluginDir: string): boolean {\n  return CANDIDATES.some(c => {\n    const p = path.join(pluginDir, c);\n    return fs.existsSync(p) && fs.statSync(p).isFile();\n  });\n}\n// if false, pass an explicit `entry` option","typeGuard":null,"tryCatchPattern":"try {\n  await installPlugin(dir);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Could not find a plugin entry file')) {\n    // fall back to explicit entry\n    return installPlugin(dir, { entry: 'src/main.ts' });\n  }\n  throw err;\n}","preventionTips":["Follow the convention: keep an index.ts at the plugin root.","Pass an explicit `entry` whenever the layout is non-standard.","Install from the source directory, not dist/ or a parent folder."],"tags":["plugins","filesystem","convention","configuration"],"backgroundTag":"plugin-entry-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}