rolldown/rolldown · error · Error

Expected the standalone runtime to start with a helper…

Error message

Expected the standalone runtime to start with a helper import

What it means

Build-time invariant in getDefaultDevRuntime: when assembling the dev runtime source, the code strips the public entry's generated first line (a helper import for standalone ESM use) before appending to the internal runtime module. If that first line is not the expected helper import, the assumption about the generated runtime entry is violated and the error is thrown. The input at fault is the generated runtime entry file's first line.

Solutions

1. Rebuild the runtime entry (the build step that generates `__RUNTIME_STRING__` / the public entry) so its first line is the expected helper import
2. If the runtime entry format changed intentionally, update the first-line check and stripping logic together

When it happens

Trigger: Thrown at packages/rolldown/src/utils/default-dev-runtime.ts:18 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rolldown/rolldown@91b44b9d7b (2026-09-07). Data as JSON: /api/errors/b1c8b68a02a5ea04. Report an issue: GitHub.

Appendix: source

Thrown at packages/rolldown/src/utils/default-dev-runtime.ts:18

import fs from 'node:fs';
import { fileURLToPath } from 'node:url';

// defined in the build step
declare const __RUNTIME_STRING__: string | undefined;

// The public entry's generated first line imports helpers for standalone ESM use. Remove it before
// appending the source to Rolldown's internal runtime module, where those helpers are already in
// scope.
export function getDefaultDevRuntime(host = 'localhost', port = 3000): string {
  if (typeof __RUNTIME_STRING__ !== 'undefined') {
    return __RUNTIME_STRING__.replaceAll('$ADDR', `${host}:${port}`);
  }

  const runtimeEntry = fs.readFileSync(fileURLToPath(import.meta.resolve('#runtime')), 'utf8');
  const runtimeHelperImportEnd = runtimeEntry.indexOf('\n');
  if (!runtimeEntry.startsWith('import ') || runtimeHelperImportEnd === -1) {
    throw new Error('Expected the standalone runtime to start with a helper import');
  }
  const runtime = runtimeEntry.slice(runtimeHelperImportEnd + 1);
  const defaultRuntime = fs.readFileSync(
    fileURLToPath(import.meta.resolve('#default-runtime')),
    'utf8',
  );
  return `${runtime}\n${defaultRuntime.replaceAll('$ADDR', `${host}:${port}`)}`;
}

View on GitHub (pinned to 91b44b9d7b)