facebook/relay · error

Watchman subscription error: {err}

Error message

Watchman subscription error: {err}

What it means

The watch-mode file watching thread panics when the Watchman subscription returns an Err. Watchman is used to observe source file changes; a subscription failure kills that worker thread, interrupting continuous compilation.

Source

Thrown at compiler/crates/relay-compiler/src/compiler.rs:319

                            Ok(FileSourceSubscriptionNextChange::TestSourceControlUpdateEnter) => {
                                info!("Test: source control update started...");
                                source_control_update_status.mark_as_started();
                            }
                            Ok(FileSourceSubscriptionNextChange::TestSourceControlUpdateLeave) => {
                                info!("Test: source control update completed.");
                                source_control_update_status.set_to_default();
                                if restart_recheck_pending_for_subscription.swap(false, SeqCst) {
                                    notify_sender.notify_one();
                                }
                            }
                            Ok(FileSourceSubscriptionNextChange::TestSourceControlUpdate) => {
                                info!("Test: source control update with new base revision...");
                                source_control_update_status.mark_as_completed();
                                notify_sender.notify_one();
                                break;
                            }
                            Err(err) => {
                                panic!("Watchman subscription error: {err}");
                            }
                        }
                    }
                });

                Ok((compiler_state, notify_receiver, subscription_handle, restart_recheck_pending))

            }
            .await;

            match result {
                Ok((
                    mut compiler_state,
                    notify_receiver,
                    subscription_handle,
                    restart_recheck_pending,
                )) => {
                    let mut red_to_green = RedToGreen::new();

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Run `watchman watch-del-all` then `watchman shutdown-server` and restart the compiler
2. Ensure Watchman is installed, running (`watchman version`), and the project is inside a watchable path
3. Fix watched-directory issues (inotify limits, permissions, deleted source roots) or disable watch mode and run a single compile

Example fix

// shell
watchman watch-del-all
watchman shutdown-server
# then restart
relay-compiler --watch

# Validate Watchman before starting watch mode
watchman version || { echo 'watchman not running'; exit 1; }
watchman watch-project .

try {
  startRelayWatch();
} catch (e) {
  if (/Watchman subscription error/.test(String(e))) {
    execSync('watchman watch-del-all');
    execSync('watchman shutdown-server');
    startRelayWatch(); // retry once, else fall back to non-watch build
  } else throw e;
}

When it happens

Trigger: Inside watch(), the spawned subscription thread receives Err(err) from a Watchman subscription event/request and calls panic!("Watchman subscription error: {err}").

Common situations: Watchman daemon not running or crashed, watchman project not settled (`watchman watch-del-all`), file limit/permission issues in the watched directory, or Watchman socket/env problems (TMPDIR mismatches).

Related errors

• Unexpected DynamicImport
• Unexpected RelayResolver
• Expected an IR that models a type
• Expected an IR that models a field
• Expected to have access to AST and docblock sources.

AI-assisted analysis of facebook/relay@668b1b85e0 (2026-09-02). Data as JSON: /api/errors/aae80508a449d380. Report an issue: GitHub.