denoland/deno · error · anyhow::Error

Cannot use --watch with an npm package whose bin entry is a

Error message

Cannot use --watch with an npm package whose bin entry is a native executable: {main_module}

What it means

`deno run --watch` restarts the program when watched files change, which requires a JavaScript entry point. When the main module is an `npm:` package, Deno resolves its bin entry and reads the first bytes (`is_native_binary` checking ELF/PE/Mach-O magic); a compiled executable cannot be reloaded on change, so the --watch combination is rejected up front.

Source

Thrown at cli/tools/run/mod.rs:327

      watcher_communicator.show_path_changed(changed_paths.clone());
      Ok(async move {
        let factory = CliFactory::from_flags_for_watcher(
          flags,
          watcher_communicator.clone(),
        );
        let cli_options = factory.cli_options()?;
        let main_module = cli_options.resolve_main_module()?;
        let preload_modules = cli_options.preload_modules()?;
        let require_modules = cli_options.require_modules()?;

        if main_module.scheme() == "npm" {
          set_npm_user_agent();
        }

        maybe_npm_install(&factory).await?;

        if is_npm_native_bin(&factory, main_module).await? {
          return Err(deno_core::anyhow::anyhow!(
            "Cannot use --watch with an npm package whose bin entry is a native executable: {main_module}"
          ));
        }

        let _ = watcher_communicator.watch_paths(cli_options.watch_paths());

        let mut worker = factory
          .create_cli_main_worker_factory()
          .await?
          .create_main_worker(
            mode,
            main_module.clone(),
            preload_modules,
            require_modules,
          )
          .await?;

        let exit_code = if watch_flags.hmr {

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Drop --watch for native-bin npm packages: run `deno run npm:<pkg> ...` once per invocation
2. Pair an external file watcher (watchexec, fswatch, watch) with the deno command instead
3. Switch to a JS-implemented equivalent package if you truly need reload-on-change

Example fix

# before
deno run --watch npm:esbuild --bundle src/main.ts
# after — run without watch, or wrap with an external watcher
deno run npm:esbuild --bundle src/main.ts
watchexec -e ts -- deno run npm:esbuild --bundle src/main.ts

When it happens

Trigger: `deno run --watch npm:<package>` where the package's bin entry is a native binary (e.g. esbuild or other Rust/Go-distributed CLIs) instead of a JS shim.

Common situations: Wrapping native CLIs in a deno watch loop during development; porting npm-exec-watch-style workflows to Deno.

Related errors

• Lint watch on standard input is not supported.
• Unable to choose binary for {} Available bins: {}
• The bench name can't be empty
• invalid doc test hashbang: #!/bin/sh (binary basename needs
• invalid doc test hashbang: #!/usr/bin/env -S deno run --allo

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/fb0d75546477ac19. Report an issue: GitHub.