denoland/deno · error

Cross compiling with snapshot is not supported.

Error message

Cross compiling with snapshot is not supported.

What it means

Build-script panic in cli/build.rs. Deno's default builds embed a V8 startup snapshot that was generated on the build host; a snapshot built for the host architecture will not run on a different TARGET. Unless the cross-build check is explicitly skipped, building the deno crate for a target triple different from HOST aborts with this message.

Source

Thrown at cli/build.rs:558

  check_appimage_runtime_hashes();
  compress_appimage_runtimes(&out_dir);

  // Skip building from docs.rs.
  if env::var_os("DOCS_RS").is_some() {
    return;
  }

  deno_napi::print_linker_flags("deno");
  deno_webgpu::print_linker_flags("deno");

  // Host snapshots won't work when cross compiling.
  let target = env::var("TARGET").unwrap();
  let host = env::var("HOST").unwrap();
  let skip_cross_check =
    env::var("DENO_SKIP_CROSS_BUILD_CHECK").is_ok_and(|v| v == "1");
  if !skip_cross_check && target != host {
    panic!("Cross compiling with snapshot is not supported.");
  }

  // To debug snapshot issues uncomment:
  // op_fetch_asset::trace_serializer();

  emit_startup_order_link_args(&out_dir);
  process_node_types(&out_dir);

  // Always emit rerun-if-changed for dts files (they are included via
  // include_str! in debug mode). Without this, cargo may use stale
  // cached artifacts when dts files change.
  emit_dts_rerun_if_changed();

  if !cfg!(debug_assertions) && std::env::var("CARGO_FEATURE_HMR").is_err() {
    compress_sources(&out_dir);
  }

  if let Ok(c) = env::var("DENO_CANARY") {

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. If you know the snapshot is valid for the target (e.g. you supplied one), opt out of the guard: `export DENO_SKIP_CROSS_BUILD_CHECK=1`
2. Otherwise build natively on/emulate the target platform (QEMU, native runner, cross toolchain with a target-generated snapshot)
3. Check Deno's official release workflow for the supported way to produce target binaries

Example fix

# before
cargo build --release --target aarch64-unknown-linux-gnu  # panics
# after
export DENO_SKIP_CROSS_BUILD_CHECK=1
cargo build --release --target aarch64-unknown-linux-gnu

T=$(rustc -vV | awk '/^host:/ {print $2}')
if [ -n "${CARGO_BUILD_TARGET:-}" ] && [ "$CARGO_BUILD_TARGET" != "$T" ]; then
  export DENO_SKIP_CROSS_BUILD_CHECK=1   # only if the snapshot is known-valid for the target
fi

When it happens

Trigger: Running `cargo build --target <other-triple>` (e.g. host x86_64-linux building aarch64-linux) where TARGET != HOST while the snapshot feature is enabled, without DENO_SKIP_CROSS_BUILD_CHECK=1.

Common situations: Packagers cross-compiling Deno for ARM boards or musl from an x86_64 host; CI matrix jobs that set --target for smoke tests; contributors experimenting with foreign targets.

Related errors

• Expected the second argument to assertSnapshot() to be an op
• Snapshot serializer must return a string
• Missing snapshot file.
• Missing snapshot: ${name}
• Snapshot does not match:\n\n ${green("[Diff]")} ${green("

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/b1d782b2abed12db. Report an issue: GitHub.