rust-lang/mdBook · error

unsupported watcher {s}

Error message

unsupported watcher {s}

What it means

The WatcherKind::from_str parser in mdbook's watch command accepts exactly "poll" or "native" for the watcher implementation; any other value panics with `unsupported watcher {s}`. There is no graceful CLI validation, so an invalid --watcher argument crashes with this panic instead of an argument error.

Source

Thrown at src/cmd/watch.rs:31

    Command::new("watch")
        .about("Watches a book's files and rebuilds it on changes")
        .arg_dest_dir()
        .arg_root_dir()
        .arg_open()
        .arg_watcher()
}

pub enum WatcherKind {
    Poll,
    Native,
}

impl WatcherKind {
    pub fn from_str(s: &str) -> WatcherKind {
        match s {
            "poll" => WatcherKind::Poll,
            "native" => WatcherKind::Native,
            _ => panic!("unsupported watcher {s}"),
        }
    }
}

// Watch command implementation
pub fn execute(args: &ArgMatches) -> Result<()> {
    let book_dir = get_book_dir(args);
    let mut book = MDBook::load(&book_dir)?;

    let update_config = |book: &mut MDBook| {
        set_dest_dir(args, book);
    };
    update_config(&mut book);

    if args.get_flag("open") {
        book.build()?;
        let path = book.build_dir_for("html").join("index.html");
        if !path.exists() {

View on GitHub (pinned to dc21064fc2)

Solutions

1. Use exactly --watcher native or --watcher poll on the command line.
2. Fix typos in scripts/aliases that pass the watcher value.
3. If the platform has native-watcher issues, use --watcher poll which works everywhere.
4. If writing integrations, validate the string against {poll,native} before calling from_str.

Example fix

// before
mdbook serve --watcher notify

// after
mdbook serve --watcher native

const WATCHERS: [&str; 2] = ["poll", "native"];
fn valid_watcher(s: &str) -> bool { WATCHERS.contains(&s) }
assert!(valid_watcher(args.watcher), "--watcher must be 'poll' or 'native'");

fn is_watcher_kind(s: &str) -> Option<&'static str> {
    match s {
        "poll" | "native" => Some(s),
        _ => None,
    }
}

// invoke via CLI wrapper that parses the flag first
if let Err(e) = parse_watcher_flag(cli_args) {
    eprintln!("invalid --watcher value: {e}; use 'poll' or 'native'");
    std::process::exit(2);
}

When it happens

Trigger: Running mdbook watch/serve with a watcher value other than "poll" or "native" (e.g. mdbook serve --watcher notify, --watcher auto, or a typo like --watcher natve), or calling WatcherKind::from_str programmatically with arbitrary strings.

Common situations: Typo in a script or alias, copying a flag value from another tool, stale documentation referencing a removed watcher name, or an old wrapper script predating the current flag values.

Related errors

• invalid key `{name}`
• The BookBuilder should always create a valid book. If you ar
• Chapter not found: {}
• Command string was empty
• internal error: expected `{lookup_key:?}` to be in root map

AI-assisted analysis of rust-lang/mdBook@dc21064fc2 (2026-09-01). Data as JSON: /api/errors/6d2a9e1b4678930f. Report an issue: GitHub.