abhigyanpatwari/GitNexus · error · WatchControlReloadError

Ignore controls remain invalid; fix them before indexing…

Error message

Ignore controls remain invalid; fix them before indexing more changes.

What it means

startWatchFileLoop() periodically re-creates the ignore predicate via createWatchIgnorePredicate(). If that throws while the controls were already invalid on the previous attempt (retryingInvalidControls is true), it wraps the failure in a WatchControlReloadError with this message, telling the user their ignore configuration (.gitnexusignore or similar) is persistently broken and watch mode aborts rather than indexing with wrong ignore rules.

Solutions

  1. Fix or restore the ignore file (syntax and permissions) named in the wrapped cause.
  2. Run a one-shot `gitnexus analyze` to see the underlying ignore-control error directly.
  3. Restart watch mode after the ignore controls validate successfully.
  4. Check file permissions on the repo and the ignore path if the cause is EACCES/ENOENT.

Example fix

// before (.gitnexusignore with unbalanced bracket)
[foo
// after
foo/
node_modules/
Defensive patterns

Strategy: try-catch

Validate before calling

try { createWatchIgnorePredicate(repoPath); } catch (e) { console.error('ignore controls invalid:', e.message); process.exit(1); } // run before starting watch

Try / catch

try {
  await runWatch();
} catch (e) {
  if (e instanceof WatchControlReloadError && /remain invalid/.test(e.message)) {
    console.error('Fix ignore controls:', e.cause?.message);
    process.exitCode = 1;
  } else throw e;
}

Prevention

When it happens

Trigger: Two consecutive failures to build the ignore predicate during watch mode — typically a malformed ignore file or unreadable ignore path — where the first failure was tolerated and the retry also failed.

Common situations: Editing .gitnexusignore while watch is running and introducing a syntax/permission error, deleting the ignore file referenced by config, or a filesystem permission change mid-watch.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-08). Data as JSON: /api/errors/7a7175e073e359f1. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/cli/analyze-watch.ts:279

  refresh: (paths: readonly string[]) => Promise<void>,
  onError: WatchRefreshError,
  onWatcherError: (error: unknown) => void = (error) => onError(error, []),
): Promise<WatchFileLoop> {
  let ignorePath = await createWatchIgnorePredicate(repoPath);
  let ignoreControlValid = true;
  let rearmPending = false;
  let closed = false;
  const queue = new WatchRefreshQueue(
    async (paths) => {
      if (paths.some(isIgnoreControlPath) || !ignoreControlValid) {
        const retryingInvalidControls = !ignoreControlValid;
        try {
          ignorePath = await createWatchIgnorePredicate(repoPath);
          ignoreControlValid = true;
          rearmPending = true;
        } catch (error) {
          ignoreControlValid = false;
          throw new WatchControlReloadError(
            retryingInvalidControls
              ? new Error(
                  'Ignore controls remain invalid; fix them before indexing more changes.',
                  {
                    cause: error,
                  },
                )
              : error,
          );
        }
      }
      // Re-arm before refreshing, never after: the refresh reads the whole
      // repository, so a write that lands while the replacement watcher is
      // arming is still picked up by this refresh, and a write that lands
      // afterwards is reported by the armed watcher.
      if (rearmPending) await rearmWatcher();
      await refresh(paths);
    },

View on GitHub (pinned to ac9a4e9abd)