fix(core): error with helpful error instead of looping nx invocations (#34820)

AgentEnder · graphite-app[bot] · nx-cloud[bot] · web-flow · commit b3edd3dd23cd · 2026-05-07T22:55:03.000-04:00
Co-authored-by: graphite-app[bot] &lt;96075541+graphite-app[bot]@users.noreply.github.com&gt;
Co-authored-by: nx-cloud[bot] &lt;71083854+nx-cloud[bot]@users.noreply.github.com&gt;
Co-authored-by: AgentEnder &lt;AgentEnder@users.noreply.github.com&gt;
diff --git a/astro-docs/src/content/docs/reference/environment-variables.mdoc b/astro-docs/src/content/docs/reference/environment-variables.mdoc
@@ -53,6 +53,7 @@ The following environment variables are ones that you can set to change the beha
 | `NX_FORCE_REUSE_CACHED_GRAPH`              | boolean | If set to `true`, Nx will reuse an existing cached project graph when available and skip recomputing it. Useful in short-lived CI steps that run immediately after a step which already computed the graph.                                                                                          |
 | `NX_FORMAT_SORT_TSCONFIG_PATHS`            | boolean | If set to `true`, generators will sort the TypeScript path mappings in the root tsconfig file.                                                                                                                                                                                                       |
 | `NX_GENERATE_QUIET`                        | boolean | If set to `true`, will prevent Nx logging file operations during generate                                                                                                                                                                                                                            |
+| `NX_INVOCATION_ROOT_PID`                   | number  | Internal. Set by Nx to the PID of the root Nx process. Used to detect recursive task invocation loops across nested Nx processes. Do not set this manually.                                                                                                                                          |
 | `NX_ISOLATE_PLUGINS`                       | boolean | Forces plugin isolation on or off, overriding the automatic detection. Set to `true` to always run inference plugins in isolated workers, or `false` to always run them in-process.                                                                                                                  |
 | `NX_MIGRATE_INSTALL_CONCURRENCY`           | number  | Limits the number of concurrent package installs when fetching migration metadata. Useful for avoiding package manager cache conflicts on Windows with private registries. If not set, installs run with no concurrency limit.                                                                       |
 | `NX_MIGRATE_SKIP_REGISTRY_FETCH`           | boolean | If set to `true`, will skip fetching metadata from the registry and instead use the installation method directly.                                                                                                                                                                                    |
diff --git a/packages/nx/src/native/db/initialize.rs b/packages/nx/src/native/db/initialize.rs
@@ -2,6 +2,7 @@ use crate::native::db::connection::NxDbConnection;
 use crate::native::tasks::details::SCHEMA as TASK_DETAILS_SCHEMA;
 use crate::native::tasks::running_tasks_service::SCHEMA as RUNNING_TASKS_SCHEMA;
 use crate::native::tasks::task_history::SCHEMA as TASK_HISTORY_SCHEMA;
+use crate::native::tasks::task_invocation_tracker::SCHEMA as TASK_INVOCATIONS_SCHEMA;
 use rusqlite::vtab::array;
 use rusqlite::{Connection, OpenFlags};
 use std::fs::{File, remove_file, write};
@@ -10,7 +11,7 @@ use std::path::{Path, PathBuf};
 use tracing::{debug, trace};
 
 /// Bump this ONLY when the database schema changes.
-pub const DB_VERSION: &str = "2";
+pub const DB_VERSION: &str = "3";
 
 // Error reporting constants - static strings to avoid allocations in error paths
 const REPORTING_INSTRUCTIONS_PERSISTENT: &str = "If the issue persists, please help us improve Nx by capturing logs and reporting this issue:\n\
@@ -197,6 +198,7 @@ fn create_all_tables(c: &mut NxDbConnection) -> anyhow::Result<()> {
         // Order matters: tables with no FK dependencies first
         conn.execute_batch(TASK_DETAILS_SCHEMA)?;
         conn.execute_batch(RUNNING_TASKS_SCHEMA)?;
+        conn.execute_batch(TASK_INVOCATIONS_SCHEMA)?;
 
         // Metadata table (used by telemetry for session tracking)
         conn.execute_batch(
diff --git a/packages/nx/src/native/index.d.ts b/packages/nx/src/native/index.d.ts
@@ -206,6 +206,18 @@ export declare class TaskHasher {
   hashPlans(hashPlans: ExternalObject<Record<string, Array<HashInstruction>>>, perTaskEnvs: Record<string, Record<string, string>>, cwd: string, collectTaskInputs?: boolean | undefined | null): Record<string, HashDetails>
 }
 
+export declare class TaskInvocationTracker {
+  constructor(db: ExternalObject<NxDbConnection>, rootPid: number)
+  /** Register a task as invoked. Throws if the task was already registered (loop detected). */
+  registerTask(parentPid: number, taskId: string): void
+  /** Remove a task invocation record after task completes. */
+  unregisterTask(taskId: string): void
+  /** Get all invocations for this root_pid, ordered by creation time. */
+  getInvocationChain(): Array<InvocationRecord>
+  /** Clean up stale invocations older than 1 day (handles PID recycling). */
+  cleanupStale(): void
+}
+
 export declare class Watcher {
   origin: string
   /**
@@ -454,6 +466,11 @@ export declare function installNxConsole(): Promise<boolean>
 
 export declare function installNxConsoleForEditor(editor: SupportedEditor): Promise<boolean>
 
+export interface InvocationRecord {
+  parentPid: number
+  taskId: string
+}
+
 export const IS_WASM: boolean
 
 /**
diff --git a/packages/nx/src/native/native-bindings.js b/packages/nx/src/native/native-bindings.js
@@ -591,6 +591,7 @@ module.exports.RunningTasksService = nativeBinding.RunningTasksService
 module.exports.RustPseudoTerminal = nativeBinding.RustPseudoTerminal
 module.exports.TaskDetails = nativeBinding.TaskDetails
 module.exports.TaskHasher = nativeBinding.TaskHasher
+module.exports.TaskInvocationTracker = nativeBinding.TaskInvocationTracker
 module.exports.Watcher = nativeBinding.Watcher
 module.exports.WorkspaceContext = nativeBinding.WorkspaceContext
 module.exports.BatchStatus = nativeBinding.BatchStatus
diff --git a/packages/nx/src/native/tasks/mod.rs b/packages/nx/src/native/tasks/mod.rs
@@ -13,3 +13,5 @@ pub mod details;
 pub mod running_tasks_service;
 #[cfg(not(target_arch = "wasm32"))]
 pub mod task_history;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod task_invocation_tracker;
diff --git a/packages/nx/src/native/tasks/task_invocation_tracker.rs b/packages/nx/src/native/tasks/task_invocation_tracker.rs
@@ -0,0 +1,101 @@
+use crate::native::db::connection::NxDbConnection;
+use napi::bindgen_prelude::External;
+use rusqlite::params;
+use std::sync::{Arc, Mutex};
+use tracing::debug;
+
+pub const SCHEMA: &str = "CREATE TABLE IF NOT EXISTS task_invocations (
+    root_pid INTEGER NOT NULL,
+    parent_pid INTEGER NOT NULL,
+    task_id TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (root_pid, task_id)
+);";
+
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct InvocationRecord {
+    pub parent_pid: u32,
+    pub task_id: String,
+}
+
+#[napi]
+pub struct TaskInvocationTracker {
+    db: Arc<Mutex<NxDbConnection>>,
+    root_pid: u32,
+}
+
+#[napi]
+impl TaskInvocationTracker {
+    #[napi(constructor)]
+    pub fn new(
+        #[napi(ts_arg_type = "ExternalObject<NxDbConnection>")] db: &External<
+            Arc<Mutex<NxDbConnection>>,
+        >,
+        root_pid: u32,
+    ) -> anyhow::Result<Self> {
+        Ok(Self {
+            db: Arc::clone(db),
+            root_pid,
+        })
+    }
+
+    /// Register a task as invoked. Throws if the task was already registered (loop detected).
+    #[napi]
+    pub fn register_task(&self, parent_pid: u32, task_id: String) -> anyhow::Result<()> {
+        self.db.lock().unwrap().execute(
+            "INSERT INTO task_invocations (root_pid, parent_pid, task_id) VALUES (?1, ?2, ?3)",
+            params![self.root_pid, parent_pid, task_id],
+        )?;
+        debug!(
+            "Registered task invocation: root_pid={}, parent_pid={}, task_id={}",
+            self.root_pid, parent_pid, &task_id
+        );
+        Ok(())
+    }
+
+    /// Remove a task invocation record after task completes.
+    #[napi]
+    pub fn unregister_task(&self, task_id: String) -> anyhow::Result<()> {
+        self.db.lock().unwrap().execute(
+            "DELETE FROM task_invocations WHERE root_pid = ?1 AND task_id = ?2",
+            params![self.root_pid, task_id],
+        )?;
+        debug!(
+            "Unregistered task invocation: root_pid={}, task_id={}",
+            self.root_pid, &task_id
+        );
+        Ok(())
+    }
+
+    /// Get all invocations for this root_pid, ordered by creation time.
+    #[napi]
+    pub fn get_invocation_chain(&self) -> anyhow::Result<Vec<InvocationRecord>> {
+        let db = self.db.lock().unwrap();
+        let mut stmt = db.prepare(
+            "SELECT parent_pid, task_id FROM task_invocations WHERE root_pid = ?1 ORDER BY created_at ASC",
+        )?;
+        let records = stmt
+            .query_map(params![self.root_pid], |row| {
+                Ok(InvocationRecord {
+                    parent_pid: row.get(0)?,
+                    task_id: row.get(1)?,
+                })
+            })?
+            .collect::<Result<Vec<_>, _>>()?;
+        Ok(records)
+    }
+
+    /// Clean up stale invocations older than 1 day (handles PID recycling).
+    #[napi]
+    pub fn cleanup_stale(&self) -> anyhow::Result<()> {
+        let deleted = self.db.lock().unwrap().execute(
+            "DELETE FROM task_invocations WHERE created_at < datetime('now', '-1 day')",
+            [],
+        )?;
+        if deleted > 0 {
+            debug!("Cleaned up {} stale invocation records", deleted);
+        }
+        Ok(())
+    }
+}
diff --git a/packages/nx/src/tasks-runner/task-env.spec.ts b/packages/nx/src/tasks-runner/task-env.spec.ts
@@ -1,9 +1,73 @@
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { getEnvFilesForTask, loadAndExpandDotEnvFile } from './task-env';
-import { Task } from '../config/task-graph';
 import { ProjectGraph } from '../config/project-graph';
+import { Task } from '../config/task-graph';
+import {
+  getEnvFilesForTask,
+  getEnvVariablesForTask,
+  loadAndExpandDotEnvFile,
+} from './task-env';
+
+describe('NX_INVOCATION_ROOT_PID', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.NX_INVOCATION_ROOT_PID;
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  function makeTask(
+    project: string,
+    target: string,
+    configuration?: string
+  ): Task {
+    let id = `${project}:${target}`;
+    if (configuration) {
+      id += `:${configuration}`;
+    }
+    return {
+      id,
+      target: { project, target, configuration },
+      overrides: {},
+      outputs: [],
+      projectRoot: `libs/${project}`,
+    } as any as Task;
+  }
+
+  it('should set NX_INVOCATION_ROOT_PID to current process PID when no existing root PID', () => {
+    const task = makeTask('workspace', 'dev');
+    const env = getEnvVariablesForTask(
+      task,
+      {},
+      'true',
+      false,
+      false,
+      '',
+      false
+    );
+    expect(env.NX_INVOCATION_ROOT_PID).toBe(String(process.pid));
+  });
+
+  it('should preserve NX_INVOCATION_ROOT_PID from parent Nx process', () => {
+    process.env.NX_INVOCATION_ROOT_PID = '12345';
+    const task = makeTask('workspace', 'dev');
+    const env = getEnvVariablesForTask(
+      task,
+      {},
+      'true',
+      false,
+      false,
+      '',
+      false
+    );
+    expect(env.NX_INVOCATION_ROOT_PID).toBe('12345');
+  });
+});
 
 describe(loadAndExpandDotEnvFile.name, () => {
   let tempDir: string;
diff --git a/packages/nx/src/tasks-runner/task-env.ts b/packages/nx/src/tasks-runner/task-env.ts
@@ -1,9 +1,9 @@
-import { Task } from '../config/task-graph';
 import { config as loadDotEnvFile } from 'dotenv';
 import { expand } from 'dotenv-expand';
-import { workspaceRoot } from '../utils/workspace-root';
 import { join } from 'node:path';
 import { ProjectGraph } from '../config/project-graph';
+import { Task } from '../config/task-graph';
+import { workspaceRoot } from '../utils/workspace-root';
 import { getEnvPathsForTask } from './task-env-paths';
 
 export function getEnvVariablesForBatchProcess(
@@ -130,6 +130,10 @@ function getNxEnvVariablesForTask(
     env.NX_TERMINAL_CAPTURE_STDERR = 'true';
   }
 
+  // Pass the root Nx process PID to nested processes for DB-based loop detection.
+  // The root PID is used as a key in the task_invocations table to track which tasks
+  // have been invoked across nested Nx processes.
+
   return {
     ...getNxEnvVariablesForForkedProcess(
       forceColor,
@@ -141,6 +145,9 @@ function getNxEnvVariablesForTask(
     ...env,
     // Ensure the TUI does not get spawned within the TUI if ever tasks invoke Nx again
     NX_TUI: 'false',
+    // tracks the root PID for child nx tasks, used to verify nx is infinitely recursing through the same tasks
+    NX_INVOCATION_ROOT_PID:
+      process.env.NX_INVOCATION_ROOT_PID ?? String(process.pid),
   };
 }
 
diff --git a/packages/nx/src/tasks-runner/task-orchestrator.ts b/packages/nx/src/tasks-runner/task-orchestrator.ts
