paperclipai/paperclip · error · PluginSandboxError

Import '${modulePath}' escapes plugin root and is not allowe

Error message

Import '${modulePath}' escapes plugin root and is not allowed

What it means

Sandbox escape guard in loadModuleSync: realpath-resolved module path is not within the plugin's real root, so the import would read code outside the plugin. Blocks symlink/path traversal out of the sandbox; the escaping import specifier is at fault.

Source

Thrown at server/src/services/plugin-runtime-sandbox.ts:99

  const entrypointPath = path.resolve(options.entrypointPath);
  const pluginRoot = path.dirname(entrypointPath);

  const context = vm.createContext({
    ...DEFAULT_GLOBALS,
    ...options.allowedGlobals,
  });

  const moduleCache = new Map<string, Record<string, unknown>>();
  const allowedModules = options.allowedModules ?? {};

  const realPluginRoot = realpathSync(pluginRoot);

  const loadModuleSync = (modulePath: string): Record<string, unknown> => {
    const resolvedPath = resolveModulePathSync(path.resolve(modulePath));
    const realPath = realpathSync(resolvedPath);

    if (!isWithinRoot(realPath, realPluginRoot)) {
      throw new PluginSandboxError(
        `Import '${modulePath}' escapes plugin root and is not allowed`,
      );
    }

    const cached = moduleCache.get(realPath);
    if (cached) return cached;

    const code = readModuleSourceSync(realPath);

    if (looksLikeEsm(code)) {
      throw new PluginSandboxError(
        "Sandbox loader only supports CommonJS modules. Build plugin worker entrypoints as CJS for sandboxed loading.",
      );
    }

    const module = { exports: {} as Record<string, unknown> };
    // Cache the module before execution to preserve CommonJS cycle semantics.
    moduleCache.set(realPath, module.exports);

View on GitHub (pinned to 120ae5428f)

Solutions

1. Keep imports inside the plugin root; replace relative paths that traverse above the plugin directory ('../..') with allowed module specifiers.

When it happens

Trigger: Thrown at server/src/services/plugin-runtime-sandbox.ts:99 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/a53ebac04201d4bf. Report an issue: GitHub.