{"record":{"id":"49cb50d6cc6a2bf0","repo":"mastra-ai/mastra","slug":"local-plugin-path-does-not-exist-or-is-not-a-direc","errorCode":null,"errorMessage":"Local plugin path does not exist or is not a directory: ${localPath}","messagePattern":"Local plugin path does not exist or is not a directory: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/plugins/install.ts","lineNumber":43,"sourceCode":"  name: string;\n  path: string;\n  entry: string;\n};\n\nconst ENTRY_CANDIDATES = ['src/index.ts', 'index.ts'];\n\nexport const NON_INTERACTIVE_GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: '0' };\n\nconst NON_INTERACTIVE_EXEC_OPTIONS = { env: NON_INTERACTIVE_GIT_ENV };\n\nexport async function installLocalPlugin(\n  localPath: string,\n  scope: PluginScope,\n  options: InstallPluginOptions,\n): Promise<string> {\n  const sourcePath = path.resolve(options.projectRoot, localPath);\n  if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isDirectory()) {\n    throw new Error(`Local plugin path does not exist or is not a directory: ${localPath}`);\n  }\n\n  const entry = detectEntry(sourcePath, options.entry);\n  ensureMastraCodePackageLink(sourcePath);\n  const plugin = await loadPluginFromEntry(path.join(sourcePath, entry));\n  const registryPath = getPluginScopePaths(scope, options).registryPath;\n  const registry = removePluginRecord(loadPluginRegistry(registryPath), plugin.id);\n  const record: InstalledPluginRecord = {\n    enabled: true,\n    source: 'local',\n    specifier: localPath,\n    path: sourcePath,\n    entry,\n    ...(plugin.version ? { version: plugin.version } : {}),\n  };\n\n  savePluginRegistry(registryPath, setPluginRecord(registry, plugin.id, record));\n  return plugin.id;","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/plugins/install.ts#L25-L61","documentation":"installLocalPlugin resolves the given local path against the project root and validates it exists and is a directory before loading the plugin. If the path is missing or points to a file, installation cannot proceed and this error is thrown with the original (unresolved) path in the message.","triggerScenarios":"Calling plugin install with a local specifier (e.g. a relative path) where path.resolve(projectRoot, localPath) either does not exist on disk or fs.statSync shows it is a file, not a directory.","commonSituations":"Typo in the path; running from a different working directory than expected so the relative path resolves elsewhere; pointing at the plugin's index.ts file instead of its root directory; plugin repo not cloned yet.","solutions":["Verify the path exists: `ls <path>` from your project root; correct typos.","Pass a directory (the plugin root containing package.json), not a source file.","Use an absolute path if your process's project root differs from your shell cwd.","Clone/checkout the local plugin first if it does not exist yet."],"exampleFix":"// before\nawait sdk.plugins.install('./pluginz/my-plugin');\n\n// after (correct spelling, directory, absolute)\nawait sdk.plugins.install('/home/me/code/my-plugin');","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nimport path from 'node:path';\nexport function assertLocalPluginDir(projectRoot: string, localPath: string): void {\n  const p = path.resolve(projectRoot, localPath);\n  if (!fs.existsSync(p) || !fs.statSync(p).isDirectory()) {\n    throw new Error(`Local plugin path does not exist or is not a directory: ${localPath}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await sdk.plugins.install(localPath);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Local plugin path does not exist')) {\n    console.error(`Check the path relative to ${process.cwd()}: ${err.message}`);\n  }\n  throw err;\n}","preventionTips":["Pass absolute paths for local plugins to avoid cwd ambiguity.","Point at the plugin root directory (containing package.json), never a source file.","Verify the plugin checkout exists before scripted installs."],"tags":["filesystem","plugins","path-validation","local-install"],"backgroundTag":"path-does-not-exist","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}