halo-dev/halo · critical · Error

${root} snapshot runtime descriptor is invalid.

Error message

${root} snapshot runtime descriptor is invalid.

What it means

Thrown by validateSnapshotEntry when the snapshot entry's 'runtime' descriptor is malformed: runtime is not an object, bridge is not a lowercase kebab string (/^[a-z0-9-]+$/), global is not a valid JS identifier, or identity is neither 'singleton' nor 'shared'. The descriptor tells the ESM externalizer how the host exposes the package (the window/global name and the bridge module id), so an invalid descriptor would produce a broken import map at runtime.

Source

Thrown at ui/packages/ui-plugin-bundler-kit/src/runtime-snapshot.ts:208

    value.exports.length === 0 ||
    value.exports.some(
      (exportName) =>
        typeof exportName !== "string" || !/^[$A-Z_a-z][$\w]*$/.test(exportName)
    ) ||
    new Set(value.exports).size !== value.exports.length
  ) {
    throw new Error(`${root} snapshot exports must be unique identifiers.`);
  }
  if (
    !isRecord(value.runtime) ||
    typeof value.runtime.bridge !== "string" ||
    !/^[a-z0-9-]+$/.test(value.runtime.bridge) ||
    typeof value.runtime.global !== "string" ||
    !/^[$A-Z_a-z][$\w]*$/.test(value.runtime.global) ||
    (value.runtime.identity !== "singleton" &&
      value.runtime.identity !== "shared")
  ) {
    throw new Error(`${root} snapshot runtime descriptor is invalid.`);
  }
  return {
    version: value.version,
    exports: [...value.exports].sort(),
    runtime: {
      bridge: value.runtime.bridge,
      global: value.runtime.global,
      identity: value.runtime.identity,
    },
  };
}

function getPackageResolutionBase(providerRoot: string, sourceId?: string) {
  const cleanSourceId = sourceId?.split(/[?#]/, 1)[0];
  if (cleanSourceId && path.isAbsolute(cleanSourceId)) {
    return path.dirname(cleanSourceId);
  }
  return providerRoot;

View on GitHub (pinned to d2f5165f9c)

Solutions

1. Set runtime.bridge to a lowercase kebab string (e.g. 'halo-vue'), runtime.global to a valid identifier (e.g. 'Vue'), and runtime.identity to 'singleton' or 'shared'.
2. Cross-check the descriptor against how the host actually assigns window[global] in the console bundle.
3. Restore upstream snapshot data and upgrade the bundler kit.

Example fix

// before
runtime: { bridge: "Vue", global: "vue-router", identity: "global" }

// after
runtime: { bridge: "halo-vue", global: "Vue", identity: "singleton" }

function validateRuntimeDescriptor(root: string, runtime: unknown) {
  const r = runtime as Record<string, unknown> | null;
  if (!r || typeof r.bridge !== "string" || !/^[a-z0-9-]+$/.test(r.bridge) ||
      typeof r.global !== "string" || !/^[$A-Z_a-z][$\w]*$/.test(r.global) ||
      (r.identity !== "singleton" && r.identity !== "shared")) {
    throw new Error(`${root} snapshot runtime descriptor is invalid.`);
  }
}

function isValidRuntimeDescriptor(value: unknown): value is { bridge: string; global: string; identity: "singleton" | "shared" } {
  if (typeof value !== "object" || value === null) return false;
  const r = value as Record<string, unknown>;
  return typeof r.bridge === "string" && /^[a-z0-9-]+$/.test(r.bridge) &&
    typeof r.global === "string" && /^[$A-Z_a-z][$\w]*$/.test(r.global) &&
    (r.identity === "singleton" || r.identity === "shared");
}

When it happens

Trigger: Fires at module load when constructing HALO_HOST_RUNTIME_SNAPSHOTS if a snapshot entry.runtime is absent, has bridge 'Vue' (uppercase), global 'vue-router' (hyphen), or identity 'global'.

Common situations: A forked snapshot data file uses the wrong global var name or a camelCase bridge; a maintainer adds a new shared root but forgets the runtime descriptor; identity typo like 'singletons'.

Related errors

• ${root} snapshot version must be stable semver.
• ${root} snapshot exports must be unique identifiers.
• ${root} resolved to invalid version ${resolved.version} at $
• Unsupported shared dependency subpath ${specifier} imported
• Explicit ESM output requires a simple stable spec.requires t

AI-assisted analysis of halo-dev/halo@d2f5165f9c (2026-08-14). Data as JSON: /api/errors/2692c453f31acd41. Report an issue: GitHub.