abhigyanpatwari/GitNexus · error · WatchControlReloadError

Configuration remains invalid; fix it before indexing more c

Error message

Configuration remains invalid; fix it before indexing more changes.

What it means

Wrapped in WatchControlReloadError by watchCommandWithRunnerIdentity in watch.ts when reloading the analyze configuration (config controls) fails on the retry pass — the config was already invalid once, the watcher waited for a fix, reloaded, and the config is still invalid. Watch mode halts rather than indexing with broken configuration.

Source

Thrown at gitnexus/src/cli/watch.ts:419

      let lastSuccessfulRefreshAt: string | undefined;
      try {
        loop = await startWatchFileLoop(
          repoPath,
          debounceMs,
          async (paths) => {
            if (paths.some(isConfigControlPath) || !configControlValid) {
              const retryingInvalidConfig = !configControlValid;
              try {
                analyzeOptions = await resolveWatchOptions(
                  repoPath,
                  cliOptions,
                  baselineEnvironment,
                  reportIgnoredConfig,
                );
                configControlValid = true;
              } catch (error) {
                configControlValid = false;
                throw new WatchControlReloadError(
                  retryingInvalidConfig
                    ? new Error(
                        'Configuration remains invalid; fix it before indexing more changes.',
                        {
                          cause: error,
                        },
                      )
                    : error,
                );
              }
            }
            const startedAt = Date.now();
            const result = await runFullAnalysis(
              repoPath,
              analyzeOptions,
              {
                onProgress: () => {},
                onLog:

View on GitHub (pinned to 52924ef12c)

Solutions

Fix the underlying configuration error reported as the `cause` of this error (often a GitNexusRcError naming the exact key).
Validate .gitnexusrc types and required keys against the documented schema before saving while the watcher runs.
Restore the config file if an edit was interrupted or partially written.
Restart `analyze --watch` once the config parses cleanly; the loop resumes only after a valid reload.

Example fix

// before (.gitnexusrc saved mid-watch)
branch: 42        // branch must be a string

// after
branch: "main"

Defensive patterns

Strategy: try-catch

Validate before calling

// validate .gitnexusrc before the watcher picks it up
try {
  const cfg = await loadAnalyzeConfigStrict(repoRoot);
  console.log('config OK');
} catch (e) {
  console.error('Fix before running --watch:', e.message);
}

Try / catch

process.on('unhandledRejection', (e) => {
  if (e instanceof WatchControlReloadError && /Configuration remains invalid/.test(e.message)) {
    console.error('Config still broken after retry — fix the cause:', (e as { cause?: unknown }).cause);
  }
});

Prevention

Write .gitnexusrc edits atomically (write temp file, rename) so the watcher never sees a half-written file.
Validate the rc file with a schema check before saving during an active watch.
Ensure env-based config sources are set before starting --watch.

When it happens

Trigger: The config reload callback throws again during watch-loop rearming: .gitnexusrc has a schema/type error (e.g. a non-string path value, invalid branch name), or env-based config became invalid, and `retryingInvalidConfig` is true on the second failure.

Common situations: Saving a bad .gitnexusrc edit while analyze --watch runs (wrong types, unknown keys, bad branch names); environment changes (unset variables) invalidating config mid-watch; partially edited config files observed by the watcher.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-09-01). Data as JSON: /api/errors/bc57ab1ac27021f6. Report an issue: GitHub.