mastra-ai/mastra · error · Error

Plugin entry file does not exist: ${explicitEntry}

Error message

Plugin entry file does not exist: ${explicitEntry}

What it means

After confirming the explicit entry is an in-bounds `.ts` path, detectEntry checks that the file actually exists on disk and is a regular file. Missing files or paths that resolve to something else (symlink to nowhere, directory named `x.ts`) produce this error naming the explicit entry.

Source

Thrown at mastracode/sdk/src/plugins/install.ts:166

  }
}

export function detectEntry(pluginDir: string, explicitEntry?: string): string {
  const root = path.resolve(pluginDir);
  if (explicitEntry) {
    const entryPath = path.resolve(pluginDir, explicitEntry);
    if (!isInsideDirectory(entryPath, root)) {
      throw new Error('Plugin entry must be inside the plugin directory');
    }
    if (fs.existsSync(entryPath) && fs.statSync(entryPath).isDirectory()) {
      const nestedEntry = detectEntry(entryPath);
      return path.relative(root, path.join(entryPath, nestedEntry));
    }
    if (path.extname(entryPath) !== '.ts') {
      throw new Error('Plugin entry must be a .ts file');
    }
    if (!fs.existsSync(entryPath) || !fs.statSync(entryPath).isFile()) {
      throw new Error(`Plugin entry file does not exist: ${explicitEntry}`);
    }
    return path.relative(root, entryPath);
  }

  const manifestPlugin = getSingleManifestPlugin(pluginDir);
  if (manifestPlugin) {
    return detectEntry(pluginDir, manifestPlugin.entry);
  }

  for (const candidate of ENTRY_CANDIDATES) {
    const entryPath = path.join(pluginDir, candidate);
    if (fs.existsSync(entryPath) && fs.statSync(entryPath).isFile()) {
      return candidate;
    }
  }

  throw new Error(`Could not find a plugin entry file. Tried: ${ENTRY_CANDIDATES.join(', ')}`);
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Correct the entry path to the actual file name; run `ls src/` to confirm.
2. Check filename casing matches exactly (case-sensitive on Linux).
3. Update or remove the explicit `entry` setting after refactors and rely on auto-detection.
4. Ensure the plugin was fully cloned/checked out (file not gitignored).

Example fix

// before
{ entry: 'src/indx.ts' }

// after
{ entry: 'src/index.ts' }

import fs from 'node:fs';
import path from 'node:path';
export function assertEntryFileExists(pluginDir: string, entry: string): void {
  const p = path.resolve(pluginDir, entry);
  if (!fs.existsSync(p) || !fs.statSync(p).isFile()) {
    throw new Error(`Plugin entry file does not exist: ${entry}`);
  }
}

try {
  await installPlugin(dir, { entry });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Plugin entry file does not exist')) {
    console.error(`Verify path/case in ${dir}; available:`, fs.readdirSync(path.join(dir, 'src')));
  }
  throw err;
}

When it happens

Trigger: Calling entry/detectEntry with explicitEntry that passes the .ts check but where fs.existsSync is false or fs.statSync(...).isFile() is false — e.g. `entry: 'src/indx.ts'` (typo) or the file was deleted/renamed.

Common situations: Typo in the entry filename; file renamed during refactor; case-mismatch on case-sensitive filesystems (Index.ts vs index.ts); stale config after moving source files.

Related errors

• Could not find a plugin entry file. Tried: ${ENTRY_CANDIDATE
• Root is not approved for rendered workspace access
• Plugin at ${pluginRoot} must declare an exact pnpm version i
• Local plugin path does not exist or is not a directory: ${lo
• Plugin entry must be inside the plugin directory

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/5daf01bea8514b29. Report an issue: GitHub.