paperclipai/paperclip · error · Error

${entrypoint.name} bundle retained a non-builtin import: ${d

Error message

${entrypoint.name} bundle retained a non-builtin import: ${dependency.path}

What it means

The verified-provider entrypoint build asserts that each bundled entrypoint output is fully self-contained: every remaining import must be an externalized Node builtin. If esbuild emits an import that is neither external nor in the nodeBuiltins allowlist, the build is considered unsafe and this error is thrown.

Source

Thrown at packages/paperclip-runner/scripts/build-verified-provider-entrypoints.mjs:45

const nodeBuiltins = new Set([
  ...builtinModules,
  ...builtinModules.map((name) => `node:${name}`),
]);

function assertSelfContainedBundle(entrypoint, result) {
  const outputs = Object.entries(result.metafile.outputs).filter(
    ([, output]) => output.entryPoint !== undefined,
  );
  if (outputs.length !== 1) {
    throw new Error(
      `${entrypoint.name} bundle emitted ${outputs.length} entrypoint outputs instead of one`,
    );
  }
  const imports = outputs[0][1].imports;
  for (const dependency of imports) {
    if (!dependency.external || !nodeBuiltins.has(dependency.path)) {
      throw new Error(
        `${entrypoint.name} bundle retained a non-builtin import: ${dependency.path}`,
      );
    }
  }
}

export async function bundleVerifiedProviderEntrypoints({ write = true } = {}) {
  const results = [];
  for (const entrypoint of verifiedProviderEntrypoints) {
    const buildBundle = async (outfile, format) => {
      const result = await build({
        entryPoints: [entrypoint.source],
        outfile,
        bundle: true,
        platform: "node",
        format,
        target: "node24",
        packages: "bundle",

View on GitHub (pinned to 01ad858492)

Solutions

Inspect dependency.path in the error to identify the offending import and remove or bundle it (make esbuild inline it instead of leaving it external).
Check the esbuild configuration in the script for an 'external' entry covering that package and remove it so it gets inlined.
If the import genuinely must stay external, verify it is a Node builtin (prefer node: prefix) so it matches the nodeBuiltins allowlist.
Re-run the script after fixing to confirm the single entrypoint output has only builtin imports.

Example fix

// before (esbuild config)
build({ entryPoints: ['src/provider.ts'], external: ['some-helper-pkg'], bundle: true });
// after
build({ entryPoints: ['src/provider.ts'], bundle: true }); // some-helper-pkg now inlined

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check the bundle imports before asserting
import { analyzeMetafile } from 'esbuild';
const meta = JSON.parse(await analyzeMetafile(result, { verbose: false }));
const bad = meta.outputs.flatMap(o => o.imports).filter(i => !i.external || !(i.external.startsWith?.('node:') || BUILTINS.includes(i.external)));
if (bad.length) console.error('Non-builtin imports:', bad.map(b => b.path).join(', '));

Type guard

function isNodeBuiltinImport(dep) {
  return dep.external && (dep.path.startsWith('node:') || ['fs','path','crypto','child_process','url','util'].includes(dep.path));
}

Try / catch

try {
  await buildVerifiedEntrypoints();
} catch (err) {
  if (String(err.message).includes('retained a non-builtin import')) {
    console.error('Bundle config leak:', err.message);
  }
  throw err;
}

Prevention

Never add runtime packages to the esbuild 'external' list for these entrypoints.
Keep nodeBuiltins derived from the node: prefix check rather than a hand-maintained list.
Run the verified build in CI on every provider change.
Grep new provider code for imports of packages that should be bundled before merging.

When it happens

Trigger: Running the build-verified-provider-entrypoints script when a provider entrypoint imports a package that esbuild left as an external runtime import (marked external or unresolved) but that is not a Node builtin, so outputs[0].imports contains a non-builtin dependency.

Common situations: A new provider adapter adds an import to a dependency the bundler externalizes by mistake; a package uses a dynamic require that esbuild leaves external; the esbuild 'external' option was misconfigured.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/1130f8ce741b085e. Report an issue: GitHub.