lavalink-client 2.10.3 → 2.10.4

package/dist/index.cjs

@@ -1270,6 +1270,11 @@ function safeStringify(obj, padding = 0) {
 }
 
 // src/structures/Node.ts
+var normalizeInt = (value, fallback, min, max) => {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(parsed)));
+};
 var LavalinkNode = class _LavalinkNode {
   heartBeatPingTimestamp = 0;
   heartBeatPongTimestamp = 0;
@@ -1704,7 +1709,12 @@ var LavalinkNode = class _LavalinkNode {
       { headers }
     );
     this.socket.on("open", this.open.bind(this));
-    this.socket.on("close", (code, reason) => this.close(code, reason?.toString()));
+    this.socket.on(
+      "close",
+      (code, reason) => void this.close(code, reason?.toString()).catch((error) => {
+        this.NodeManager.emit("error", this, error);
+      })
+    );
     this.socket.on("message", this.message.bind(this));
     this.socket.on("error", this.error.bind(this));
   }
@@ -1796,43 +1806,7 @@ var LavalinkNode = class _LavalinkNode {
           )
         );
       }
-      const nodeToMove = Array.from(this.NodeManager.leastUsedNodes("playingPlayers")).find(
-        (n) => n.connected && n.options.id !== this.id
-      );
-      if (!nodeToMove) {
-        return Promise.allSettled(
-          Array.from(players.values()).map(
-            (player) => player.destroy("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */).catch((error) => {
-              this._emitDebugEvent("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */, {
-                state: "error",
-                message: `Failed to destroy player ${player.guildId}: ${error.message}`,
-                error,
-                functionLayer: "Node > destroy() > movePlayers"
-              });
-            })
-          )
-        );
-      }
-      return Promise.allSettled(
-        Array.from(players.values()).map(
-          (player) => player.changeNode(nodeToMove.options.id).catch((error) => {
-            this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
-              state: "error",
-              message: `Failed to move player ${player.guildId}: ${error.message}`,
-              error,
-              functionLayer: "Node > destroy() > movePlayers"
-            });
-            return player.destroy(error.message ?? "PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
-              this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
-                state: "error",
-                message: `Failed to destroy player ${player.guildId} after move failure: ${destroyError.message}`,
-                error: destroyError,
-                functionLayer: "Node > destroy() > movePlayers"
-              });
-            });
-          })
-        )
-      );
+      return this.movePlayersToReplacementNode(Array.from(players.values()), "destroy");
     };
     return void handlePlayerOperations().finally(() => {
       this.socket?.close(1e3, "Node-Destroy");
@@ -1871,6 +1845,247 @@ var LavalinkNode = class _LavalinkNode {
     this.resetReconnectionAttempts();
     this.NodeManager.emit("disconnect", this, { code: 1e3, reason: disconnectReason });
   }
+  /**
+   * Pick the best ready node to move players to.
+   * A node must be connected and have a sessionId before a player can be migrated to it.
+   */
+  getReadyMigrationNode(excludeNodeId) {
+    return this.selectMigrationTarget(/* @__PURE__ */ new Set([excludeNodeId]), Number.MAX_SAFE_INTEGER);
+  }
+  getMigrationErrorMessage(error) {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "string") return error;
+    try {
+      return safeStringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  getMigrationConfig() {
+    const migration = this._LManager.options?.advancedOptions?.playerMigration;
+    return {
+      concurrency: normalizeInt(migration?.concurrency, 5, 1, 32),
+      perTargetConcurrency: normalizeInt(migration?.perTargetConcurrency, 2, 1, 8),
+      backpressureDelayMs: normalizeInt(migration?.backpressureDelayMs, 50, 0, 1e3)
+    };
+  }
+  getMigrationReservationCount(nodeId) {
+    return this.NodeManager.playerMigration.reservations.get(nodeId) || 0;
+  }
+  reserveMigrationTarget(nodeId) {
+    this.NodeManager.playerMigration.reservations.set(nodeId, this.getMigrationReservationCount(nodeId) + 1);
+  }
+  releaseMigrationTarget(nodeId) {
+    const current = this.getMigrationReservationCount(nodeId);
+    if (current <= 1) this.NodeManager.playerMigration.reservations.delete(nodeId);
+    else this.NodeManager.playerMigration.reservations.set(nodeId, current - 1);
+    this.NodeManager.signalPlayerMigrationCapacityChange();
+  }
+  getEffectiveMigrationLoad(node) {
+    return (node.stats?.players || 0) + this.getMigrationReservationCount(node.id);
+  }
+  selectMigrationTarget(excludeNodeIds, perTargetConcurrency) {
+    let selectedNode = null;
+    let selectedEffectiveLoad = Number.POSITIVE_INFINITY;
+    let selectedLiveLoad = Number.POSITIVE_INFINITY;
+    for (const node of this.NodeManager.nodes.values()) {
+      if (!node.connected || !node.sessionId) continue;
+      if (excludeNodeIds.has(node.id)) continue;
+      const reservationCount = this.getMigrationReservationCount(node.id);
+      if (reservationCount >= perTargetConcurrency) continue;
+      const liveLoad = node.stats?.players || 0;
+      const effectiveLoad = this.getEffectiveMigrationLoad(node);
+      if (!selectedNode || effectiveLoad < selectedEffectiveLoad || effectiveLoad === selectedEffectiveLoad && (liveLoad < selectedLiveLoad || liveLoad === selectedLiveLoad && node.id.localeCompare(selectedNode.id) < 0)) {
+        selectedNode = node;
+        selectedEffectiveLoad = effectiveLoad;
+        selectedLiveLoad = liveLoad;
+      }
+    }
+    return selectedNode;
+  }
+  hasAnyHealthyMigrationNode(excludeNodeIds) {
+    for (const node of this.NodeManager.nodes.values()) {
+      if (!node.connected || !node.sessionId) continue;
+      if (excludeNodeIds.has(node.id)) continue;
+      return true;
+    }
+    return false;
+  }
+  isMigrationNodeHealthy(nodeId) {
+    const node = this.NodeManager.nodes.get(nodeId);
+    return !!node?.connected && !!node.sessionId;
+  }
+  async waitForMigrationCapacity(excludeNodeIds, perTargetConcurrency, timeoutMs) {
+    if (this.selectMigrationTarget(excludeNodeIds, perTargetConcurrency)) return;
+    if (timeoutMs <= 0) {
+      await new Promise((resolve) => setImmediate(resolve));
+      return;
+    }
+    await new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const onSignal = () => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        this.NodeManager.playerMigration.capacityWaiters.delete(onSignal);
+        resolve();
+      };
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.NodeManager.playerMigration.capacityWaiters.delete(onSignal);
+        resolve();
+      }, timeoutMs);
+      this.NodeManager.playerMigration.capacityWaiters.add(onSignal);
+    });
+  }
+  /**
+   * Move a batch of players to a ready node with bounded concurrency.
+   * This keeps migration responsive without flooding the replacement node with requests.
+   */
+  async movePlayersToReplacementNode(players, onNoEligibleNode) {
+    const migrationQueue = players.filter((player) => {
+      if (player.getData("internal_nodeMigrating") === true) return false;
+      if (player.getData("internal_destroystatus") === true) return false;
+      player.setData("internal_nodeMigrating", true);
+      return true;
+    });
+    const { concurrency, perTargetConcurrency, backpressureDelayMs } = this.getMigrationConfig();
+    let nextQueueIndex = 0;
+    const workerCount = Math.min(concurrency, migrationQueue.length);
+    const migratePlayer = async (player) => {
+      const excludedNodes = /* @__PURE__ */ new Set();
+      try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+          if (player.getData("internal_destroystatus") === true) return;
+          if (player.node?.options?.id !== this.id) return;
+          let targetNode = null;
+          while (!(targetNode = this.selectMigrationTarget(excludedNodes, perTargetConcurrency))) {
+            if (!this.hasAnyHealthyMigrationNode(excludedNodes)) {
+              this._emitDebugEvent("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */, {
+                state: "warn",
+                message: `No eligible ready node was available for player ${player.guildId}`,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (onNoEligibleNode === "destroy") {
+                await player.destroy("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */).catch((destroyError) => {
+                  this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+                    state: "error",
+                    message: `Failed to destroy player ${player.guildId}: ${this.getMigrationErrorMessage(destroyError)}`,
+                    error: destroyError,
+                    functionLayer: "Node > movePlayersToReplacementNode()"
+                  });
+                });
+              } else {
+                player.playing = false;
+              }
+              return;
+            }
+            await this.waitForMigrationCapacity(excludedNodes, perTargetConcurrency, backpressureDelayMs);
+          }
+          const targetNodeId = targetNode.id;
+          if (player.getData("internal_destroystatus") === true) return;
+          if (player.node?.options?.id !== this.id) return;
+          this.reserveMigrationTarget(targetNodeId);
+          try {
+            await player.changeNode(targetNodeId);
+            return;
+          } catch (error) {
+            const errorMessage = this.getMigrationErrorMessage(error);
+            this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+              state: "error",
+              message: `Failed to move player ${player.guildId}: ${errorMessage}`,
+              error,
+              functionLayer: "Node > movePlayersToReplacementNode()"
+            });
+            const targetStillHealthy = this.isMigrationNodeHealthy(targetNodeId);
+            excludedNodes.add(targetNodeId);
+            if (attempt === 0 && !targetStillHealthy) {
+              this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+                state: "warn",
+                message: `Migration target ${targetNodeId} became unavailable while moving player ${player.guildId}; retrying on another ready node`,
+                error,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (player.node?.options?.id === targetNodeId) player.node = this;
+              continue;
+            }
+            if (attempt === 0 && this.hasAnyHealthyMigrationNode(excludedNodes)) {
+              this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+                state: "warn",
+                message: `Retrying migration for player ${player.guildId} on a different ready node`,
+                error,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (player.node?.options?.id === targetNodeId) player.node = this;
+              continue;
+            }
+            if (onNoEligibleNode === "destroy") {
+              await player.destroy("PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
+                this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+                  state: "error",
+                  message: `Failed to destroy player ${player.guildId} after unexpected migration failure: ${this.getMigrationErrorMessage(destroyError)}`,
+                  error: destroyError,
+                  functionLayer: "Node > movePlayersToReplacementNode()"
+                });
+              });
+            } else {
+              player.playing = false;
+            }
+            return;
+          } finally {
+            this.releaseMigrationTarget(targetNodeId);
+          }
+        }
+      } catch (error) {
+        this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+          state: "error",
+          message: `Unexpected error while migrating player ${player.guildId}: ${this.getMigrationErrorMessage(error)}`,
+          error,
+          functionLayer: "Node > movePlayersToReplacementNode()"
+        });
+        if (onNoEligibleNode === "destroy") {
+          await player.destroy("PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
+            this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+              state: "error",
+              message: `Failed to destroy player ${player.guildId} after unexpected migration failure: ${this.getMigrationErrorMessage(destroyError)}`,
+              error: destroyError,
+              functionLayer: "Node > movePlayersToReplacementNode()"
+            });
+          });
+        } else {
+          player.playing = false;
+        }
+      }
+    };
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (true) {
+        const queueIndex = nextQueueIndex++;
+        if (queueIndex >= migrationQueue.length) return;
+        const player = migrationQueue[queueIndex];
+        if (!player) continue;
+        try {
+          if (player.getData("internal_nodeMigrating") !== true) {
+            player.setData("internal_nodeMigrating", true);
+          }
+          if (player.getData("internal_destroystatus") === true) continue;
+          if (player.node?.options?.id !== this.id) continue;
+          await migratePlayer(player);
+        } catch (error) {
+          this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+            state: "error",
+            message: `Unexpected worker error while migrating player ${player.guildId}: ${this.getMigrationErrorMessage(error)}`,
+            error,
+            functionLayer: "Node > movePlayersToReplacementNode()"
+          });
+        } finally {
+          player.setData("internal_nodeMigrating", void 0);
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
   /**
    * Gets all Players of a Node
    * @returns array of players inside of lavalink
@@ -2583,9 +2798,10 @@ var LavalinkNode = class _LavalinkNode {
     }
     this.info.isNodelink = !!this.info.isNodelink;
     this.NodeManager.emit("connect", this);
+    this.NodeManager.signalPlayerMigrationCapacityChange();
   }
   /** @private util function for handling closing events from websocket */
-  close(code, reason) {
+  async close(code, reason) {
     this.resetAckTimeouts(true, true);
     try {
       if (this.socket) {
@@ -2604,19 +2820,22 @@ var LavalinkNode = class _LavalinkNode {
     this.isAlive = false;
     if (code === 1006 && !reason) reason = "Socket got terminated due to no ping connection";
     if (code === 1e3 && reason === "Node-Disconnect") return;
+    const players = Array.from(
+      this._LManager.players.filter((p) => p?.node?.options?.id === this?.options?.id).values()
+    );
     this.NodeManager.emit("disconnect", this, { code, reason });
     if (code !== 1e3 || reason !== "Node-Destroy") {
       if (this.NodeManager.nodes.has(this.id)) {
         this.reconnect();
       }
     }
-    this._LManager.players.filter((p) => p?.node?.options?.id === this?.options?.id).forEach((p) => {
-      if (!this._LManager.options.autoMove) return p.playing = false;
-      if (this._LManager.options.autoMove) {
-        if (this.NodeManager.nodes.filter((n) => n.connected).size === 0) return p.playing = false;
-        p.moveNode();
-      }
-    });
+    if (this._LManager.options.autoMove && players.length) {
+      await this.movePlayersToReplacementNode(players, "freeze");
+    } else if (!this._LManager.options.autoMove) {
+      players.forEach((p) => p.playing = false);
+    } else if (this.NodeManager.nodes.filter((n) => n.connected && !!n.sessionId).size === 0) {
+      players.forEach((p) => p.playing = false);
+    }
   }
   /** @private util function for handling error events from websocket */
   error(error) {
@@ -3694,6 +3913,16 @@ var NodeManager = class extends import_node_events.EventEmitter {
    * A map of all nodes in the nodeManager
    */
   nodes = new MiniMap();
+  /** @internal Coordinates player migrations between nodes owned by this manager. */
+  playerMigration = {
+    reservations: /* @__PURE__ */ new Map(),
+    capacityWaiters: /* @__PURE__ */ new Set()
+  };
+  /** @internal Wakes migrations waiting for capacity on one of this manager's nodes. */
+  signalPlayerMigrationCapacityChange() {
+    for (const resolve of this.playerMigration.capacityWaiters) resolve();
+    this.playerMigration.capacityWaiters.clear();
+  }
   /**
    * @param LavalinkManager The LavalinkManager that created this NodeManager
    */
@@ -6345,8 +6574,8 @@ var Player = class {
     try {
       if (!node)
         node = Array.from(this.LavalinkManager.nodeManager.leastUsedNodes("playingPlayers")).find(
-          (n) => n.connected && n.options.id !== this.node.options.id
-        ).id;
+          (n) => n.connected && !!n.sessionId && n.options.id !== this.node.options.id
+        )?.id;
       if (!node || !this.LavalinkManager.nodeManager.nodes.get(node))
         throw new RangeError("No nodes are available.");
       if (this.node.options.id === node) return this;
@@ -6501,6 +6730,11 @@ var LavalinkManager = class _LavalinkManager extends import_node_events2.EventEm
       advancedOptions: {
         enableDebugEvents: options?.advancedOptions?.enableDebugEvents ?? false,
         maxFilterFixDuration: options?.advancedOptions?.maxFilterFixDuration ?? 6e5,
+        playerMigration: {
+          concurrency: options?.advancedOptions?.playerMigration?.concurrency ?? 5,
+          perTargetConcurrency: options?.advancedOptions?.playerMigration?.perTargetConcurrency ?? 2,
+          backpressureDelayMs: options?.advancedOptions?.playerMigration?.backpressureDelayMs ?? 50
+        },
         debugOptions: {
           logCustomSearches: options?.advancedOptions?.debugOptions?.logCustomSearches ?? false,
           noAudio: options?.advancedOptions?.debugOptions?.noAudio ?? false,

package/dist/index.d.cts

@@ -3306,6 +3306,26 @@ declare class LavalinkNode {
      * ```
      */
     disconnect(disconnectReason?: DisconnectReasonsType): void;
+    /**
+     * Pick the best ready node to move players to.
+     * A node must be connected and have a sessionId before a player can be migrated to it.
+     */
+    private getReadyMigrationNode;
+    private getMigrationErrorMessage;
+    private getMigrationConfig;
+    private getMigrationReservationCount;
+    private reserveMigrationTarget;
+    private releaseMigrationTarget;
+    private getEffectiveMigrationLoad;
+    private selectMigrationTarget;
+    private hasAnyHealthyMigrationNode;
+    private isMigrationNodeHealthy;
+    private waitForMigrationCapacity;
+    /**
+     * Move a batch of players to a ready node with bounded concurrency.
+     * This keeps migration responsive without flooding the replacement node with requests.
+     */
+    private movePlayersToReplacementNode;
     /**
      * Gets all Players of a Node
      * @returns array of players inside of lavalink
@@ -3741,6 +3761,13 @@ declare class NodeManager extends EventEmitter {
      * A map of all nodes in the nodeManager
      */
     nodes: MiniMap<string, LavalinkNode | NodeLinkNode>;
+    /** @internal Coordinates player migrations between nodes owned by this manager. */
+    readonly playerMigration: {
+        reservations: Map<string, number>;
+        capacityWaiters: Set<() => void>;
+    };
+    /** @internal Wakes migrations waiting for capacity on one of this manager's nodes. */
+    signalPlayerMigrationCapacityChange(): void;
     /**
      * @param LavalinkManager The LavalinkManager that created this NodeManager
      */
@@ -4103,6 +4130,15 @@ interface ManagerOptions<CustomPlayerT extends Player = Player> {
                 dontThrowError?: boolean;
             };
         };
+        /** Player migration configuration */
+        playerMigration?: {
+            /** Maximum number of players migrated concurrently. Default: 5 */
+            concurrency?: number;
+            /** Maximum number of concurrent migrations to a single target node. Default: 2 */
+            perTargetConcurrency?: number;
+            /** Maximum time to wait for migration capacity before retrying. Default: 50ms */
+            backpressureDelayMs?: number;
+        };
     };
 }
 

package/dist/index.d.ts

@@ -3306,6 +3306,26 @@ declare class LavalinkNode {
      * ```
      */
     disconnect(disconnectReason?: DisconnectReasonsType): void;
+    /**
+     * Pick the best ready node to move players to.
+     * A node must be connected and have a sessionId before a player can be migrated to it.
+     */
+    private getReadyMigrationNode;
+    private getMigrationErrorMessage;
+    private getMigrationConfig;
+    private getMigrationReservationCount;
+    private reserveMigrationTarget;
+    private releaseMigrationTarget;
+    private getEffectiveMigrationLoad;
+    private selectMigrationTarget;
+    private hasAnyHealthyMigrationNode;
+    private isMigrationNodeHealthy;
+    private waitForMigrationCapacity;
+    /**
+     * Move a batch of players to a ready node with bounded concurrency.
+     * This keeps migration responsive without flooding the replacement node with requests.
+     */
+    private movePlayersToReplacementNode;
     /**
      * Gets all Players of a Node
      * @returns array of players inside of lavalink
@@ -3741,6 +3761,13 @@ declare class NodeManager extends EventEmitter {
      * A map of all nodes in the nodeManager
      */
     nodes: MiniMap<string, LavalinkNode | NodeLinkNode>;
+    /** @internal Coordinates player migrations between nodes owned by this manager. */
+    readonly playerMigration: {
+        reservations: Map<string, number>;
+        capacityWaiters: Set<() => void>;
+    };
+    /** @internal Wakes migrations waiting for capacity on one of this manager's nodes. */
+    signalPlayerMigrationCapacityChange(): void;
     /**
      * @param LavalinkManager The LavalinkManager that created this NodeManager
      */
@@ -4103,6 +4130,15 @@ interface ManagerOptions<CustomPlayerT extends Player = Player> {
                 dontThrowError?: boolean;
             };
         };
+        /** Player migration configuration */
+        playerMigration?: {
+            /** Maximum number of players migrated concurrently. Default: 5 */
+            concurrency?: number;
+            /** Maximum number of concurrent migrations to a single target node. Default: 2 */
+            perTargetConcurrency?: number;
+            /** Maximum time to wait for migration capacity before retrying. Default: 50ms */
+            backpressureDelayMs?: number;
+        };
     };
 }
 

package/dist/index.js

@@ -1204,6 +1204,11 @@ function safeStringify(obj, padding = 0) {
 }
 
 // src/structures/Node.ts
+var normalizeInt = (value, fallback, min, max) => {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(parsed)));
+};
 var LavalinkNode = class _LavalinkNode {
   heartBeatPingTimestamp = 0;
   heartBeatPongTimestamp = 0;
@@ -1638,7 +1643,12 @@ var LavalinkNode = class _LavalinkNode {
       { headers }
     );
     this.socket.on("open", this.open.bind(this));
-    this.socket.on("close", (code, reason) => this.close(code, reason?.toString()));
+    this.socket.on(
+      "close",
+      (code, reason) => void this.close(code, reason?.toString()).catch((error) => {
+        this.NodeManager.emit("error", this, error);
+      })
+    );
     this.socket.on("message", this.message.bind(this));
     this.socket.on("error", this.error.bind(this));
   }
@@ -1730,43 +1740,7 @@ var LavalinkNode = class _LavalinkNode {
           )
         );
       }
-      const nodeToMove = Array.from(this.NodeManager.leastUsedNodes("playingPlayers")).find(
-        (n) => n.connected && n.options.id !== this.id
-      );
-      if (!nodeToMove) {
-        return Promise.allSettled(
-          Array.from(players.values()).map(
-            (player) => player.destroy("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */).catch((error) => {
-              this._emitDebugEvent("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */, {
-                state: "error",
-                message: `Failed to destroy player ${player.guildId}: ${error.message}`,
-                error,
-                functionLayer: "Node > destroy() > movePlayers"
-              });
-            })
-          )
-        );
-      }
-      return Promise.allSettled(
-        Array.from(players.values()).map(
-          (player) => player.changeNode(nodeToMove.options.id).catch((error) => {
-            this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
-              state: "error",
-              message: `Failed to move player ${player.guildId}: ${error.message}`,
-              error,
-              functionLayer: "Node > destroy() > movePlayers"
-            });
-            return player.destroy(error.message ?? "PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
-              this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
-                state: "error",
-                message: `Failed to destroy player ${player.guildId} after move failure: ${destroyError.message}`,
-                error: destroyError,
-                functionLayer: "Node > destroy() > movePlayers"
-              });
-            });
-          })
-        )
-      );
+      return this.movePlayersToReplacementNode(Array.from(players.values()), "destroy");
     };
     return void handlePlayerOperations().finally(() => {
       this.socket?.close(1e3, "Node-Destroy");
@@ -1805,6 +1779,247 @@ var LavalinkNode = class _LavalinkNode {
     this.resetReconnectionAttempts();
     this.NodeManager.emit("disconnect", this, { code: 1e3, reason: disconnectReason });
   }
+  /**
+   * Pick the best ready node to move players to.
+   * A node must be connected and have a sessionId before a player can be migrated to it.
+   */
+  getReadyMigrationNode(excludeNodeId) {
+    return this.selectMigrationTarget(/* @__PURE__ */ new Set([excludeNodeId]), Number.MAX_SAFE_INTEGER);
+  }
+  getMigrationErrorMessage(error) {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "string") return error;
+    try {
+      return safeStringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  getMigrationConfig() {
+    const migration = this._LManager.options?.advancedOptions?.playerMigration;
+    return {
+      concurrency: normalizeInt(migration?.concurrency, 5, 1, 32),
+      perTargetConcurrency: normalizeInt(migration?.perTargetConcurrency, 2, 1, 8),
+      backpressureDelayMs: normalizeInt(migration?.backpressureDelayMs, 50, 0, 1e3)
+    };
+  }
+  getMigrationReservationCount(nodeId) {
+    return this.NodeManager.playerMigration.reservations.get(nodeId) || 0;
+  }
+  reserveMigrationTarget(nodeId) {
+    this.NodeManager.playerMigration.reservations.set(nodeId, this.getMigrationReservationCount(nodeId) + 1);
+  }
+  releaseMigrationTarget(nodeId) {
+    const current = this.getMigrationReservationCount(nodeId);
+    if (current <= 1) this.NodeManager.playerMigration.reservations.delete(nodeId);
+    else this.NodeManager.playerMigration.reservations.set(nodeId, current - 1);
+    this.NodeManager.signalPlayerMigrationCapacityChange();
+  }
+  getEffectiveMigrationLoad(node) {
+    return (node.stats?.players || 0) + this.getMigrationReservationCount(node.id);
+  }
+  selectMigrationTarget(excludeNodeIds, perTargetConcurrency) {
+    let selectedNode = null;
+    let selectedEffectiveLoad = Number.POSITIVE_INFINITY;
+    let selectedLiveLoad = Number.POSITIVE_INFINITY;
+    for (const node of this.NodeManager.nodes.values()) {
+      if (!node.connected || !node.sessionId) continue;
+      if (excludeNodeIds.has(node.id)) continue;
+      const reservationCount = this.getMigrationReservationCount(node.id);
+      if (reservationCount >= perTargetConcurrency) continue;
+      const liveLoad = node.stats?.players || 0;
+      const effectiveLoad = this.getEffectiveMigrationLoad(node);
+      if (!selectedNode || effectiveLoad < selectedEffectiveLoad || effectiveLoad === selectedEffectiveLoad && (liveLoad < selectedLiveLoad || liveLoad === selectedLiveLoad && node.id.localeCompare(selectedNode.id) < 0)) {
+        selectedNode = node;
+        selectedEffectiveLoad = effectiveLoad;
+        selectedLiveLoad = liveLoad;
+      }
+    }
+    return selectedNode;
+  }
+  hasAnyHealthyMigrationNode(excludeNodeIds) {
+    for (const node of this.NodeManager.nodes.values()) {
+      if (!node.connected || !node.sessionId) continue;
+      if (excludeNodeIds.has(node.id)) continue;
+      return true;
+    }
+    return false;
+  }
+  isMigrationNodeHealthy(nodeId) {
+    const node = this.NodeManager.nodes.get(nodeId);
+    return !!node?.connected && !!node.sessionId;
+  }
+  async waitForMigrationCapacity(excludeNodeIds, perTargetConcurrency, timeoutMs) {
+    if (this.selectMigrationTarget(excludeNodeIds, perTargetConcurrency)) return;
+    if (timeoutMs <= 0) {
+      await new Promise((resolve) => setImmediate(resolve));
+      return;
+    }
+    await new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const onSignal = () => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        this.NodeManager.playerMigration.capacityWaiters.delete(onSignal);
+        resolve();
+      };
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.NodeManager.playerMigration.capacityWaiters.delete(onSignal);
+        resolve();
+      }, timeoutMs);
+      this.NodeManager.playerMigration.capacityWaiters.add(onSignal);
+    });
+  }
+  /**
+   * Move a batch of players to a ready node with bounded concurrency.
+   * This keeps migration responsive without flooding the replacement node with requests.
+   */
+  async movePlayersToReplacementNode(players, onNoEligibleNode) {
+    const migrationQueue = players.filter((player) => {
+      if (player.getData("internal_nodeMigrating") === true) return false;
+      if (player.getData("internal_destroystatus") === true) return false;
+      player.setData("internal_nodeMigrating", true);
+      return true;
+    });
+    const { concurrency, perTargetConcurrency, backpressureDelayMs } = this.getMigrationConfig();
+    let nextQueueIndex = 0;
+    const workerCount = Math.min(concurrency, migrationQueue.length);
+    const migratePlayer = async (player) => {
+      const excludedNodes = /* @__PURE__ */ new Set();
+      try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+          if (player.getData("internal_destroystatus") === true) return;
+          if (player.node?.options?.id !== this.id) return;
+          let targetNode = null;
+          while (!(targetNode = this.selectMigrationTarget(excludedNodes, perTargetConcurrency))) {
+            if (!this.hasAnyHealthyMigrationNode(excludedNodes)) {
+              this._emitDebugEvent("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */, {
+                state: "warn",
+                message: `No eligible ready node was available for player ${player.guildId}`,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (onNoEligibleNode === "destroy") {
+                await player.destroy("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */).catch((destroyError) => {
+                  this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+                    state: "error",
+                    message: `Failed to destroy player ${player.guildId}: ${this.getMigrationErrorMessage(destroyError)}`,
+                    error: destroyError,
+                    functionLayer: "Node > movePlayersToReplacementNode()"
+                  });
+                });
+              } else {
+                player.playing = false;
+              }
+              return;
+            }
+            await this.waitForMigrationCapacity(excludedNodes, perTargetConcurrency, backpressureDelayMs);
+          }
+          const targetNodeId = targetNode.id;
+          if (player.getData("internal_destroystatus") === true) return;
+          if (player.node?.options?.id !== this.id) return;
+          this.reserveMigrationTarget(targetNodeId);
+          try {
+            await player.changeNode(targetNodeId);
+            return;
+          } catch (error) {
+            const errorMessage = this.getMigrationErrorMessage(error);
+            this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+              state: "error",
+              message: `Failed to move player ${player.guildId}: ${errorMessage}`,
+              error,
+              functionLayer: "Node > movePlayersToReplacementNode()"
+            });
+            const targetStillHealthy = this.isMigrationNodeHealthy(targetNodeId);
+            excludedNodes.add(targetNodeId);
+            if (attempt === 0 && !targetStillHealthy) {
+              this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+                state: "warn",
+                message: `Migration target ${targetNodeId} became unavailable while moving player ${player.guildId}; retrying on another ready node`,
+                error,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (player.node?.options?.id === targetNodeId) player.node = this;
+              continue;
+            }
+            if (attempt === 0 && this.hasAnyHealthyMigrationNode(excludedNodes)) {
+              this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+                state: "warn",
+                message: `Retrying migration for player ${player.guildId} on a different ready node`,
+                error,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (player.node?.options?.id === targetNodeId) player.node = this;
+              continue;
+            }
+            if (onNoEligibleNode === "destroy") {
+              await player.destroy("PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
+                this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+                  state: "error",
+                  message: `Failed to destroy player ${player.guildId} after unexpected migration failure: ${this.getMigrationErrorMessage(destroyError)}`,
+                  error: destroyError,
+                  functionLayer: "Node > movePlayersToReplacementNode()"
+                });
+              });
+            } else {
+              player.playing = false;
+            }
+            return;
+          } finally {
+            this.releaseMigrationTarget(targetNodeId);
+          }
+        }
+      } catch (error) {
+        this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+          state: "error",
+          message: `Unexpected error while migrating player ${player.guildId}: ${this.getMigrationErrorMessage(error)}`,
+          error,
+          functionLayer: "Node > movePlayersToReplacementNode()"
+        });
+        if (onNoEligibleNode === "destroy") {
+          await player.destroy("PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
+            this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+              state: "error",
+              message: `Failed to destroy player ${player.guildId} after unexpected migration failure: ${this.getMigrationErrorMessage(destroyError)}`,
+              error: destroyError,
+              functionLayer: "Node > movePlayersToReplacementNode()"
+            });
+          });
+        } else {
+          player.playing = false;
+        }
+      }
+    };
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (true) {
+        const queueIndex = nextQueueIndex++;
+        if (queueIndex >= migrationQueue.length) return;
+        const player = migrationQueue[queueIndex];
+        if (!player) continue;
+        try {
+          if (player.getData("internal_nodeMigrating") !== true) {
+            player.setData("internal_nodeMigrating", true);
+          }
+          if (player.getData("internal_destroystatus") === true) continue;
+          if (player.node?.options?.id !== this.id) continue;
+          await migratePlayer(player);
+        } catch (error) {
+          this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+            state: "error",
+            message: `Unexpected worker error while migrating player ${player.guildId}: ${this.getMigrationErrorMessage(error)}`,
+            error,
+            functionLayer: "Node > movePlayersToReplacementNode()"
+          });
+        } finally {
+          player.setData("internal_nodeMigrating", void 0);
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
   /**
    * Gets all Players of a Node
    * @returns array of players inside of lavalink
@@ -2517,9 +2732,10 @@ var LavalinkNode = class _LavalinkNode {
     }
     this.info.isNodelink = !!this.info.isNodelink;
     this.NodeManager.emit("connect", this);
+    this.NodeManager.signalPlayerMigrationCapacityChange();
   }
   /** @private util function for handling closing events from websocket */
-  close(code, reason) {
+  async close(code, reason) {
     this.resetAckTimeouts(true, true);
     try {
       if (this.socket) {
@@ -2538,19 +2754,22 @@ var LavalinkNode = class _LavalinkNode {
     this.isAlive = false;
     if (code === 1006 && !reason) reason = "Socket got terminated due to no ping connection";
     if (code === 1e3 && reason === "Node-Disconnect") return;
+    const players = Array.from(
+      this._LManager.players.filter((p) => p?.node?.options?.id === this?.options?.id).values()
+    );
     this.NodeManager.emit("disconnect", this, { code, reason });
     if (code !== 1e3 || reason !== "Node-Destroy") {
       if (this.NodeManager.nodes.has(this.id)) {
         this.reconnect();
       }
     }
-    this._LManager.players.filter((p) => p?.node?.options?.id === this?.options?.id).forEach((p) => {
-      if (!this._LManager.options.autoMove) return p.playing = false;
-      if (this._LManager.options.autoMove) {
-        if (this.NodeManager.nodes.filter((n) => n.connected).size === 0) return p.playing = false;
-        p.moveNode();
-      }
-    });
+    if (this._LManager.options.autoMove && players.length) {
+      await this.movePlayersToReplacementNode(players, "freeze");
+    } else if (!this._LManager.options.autoMove) {
+      players.forEach((p) => p.playing = false);
+    } else if (this.NodeManager.nodes.filter((n) => n.connected && !!n.sessionId).size === 0) {
+      players.forEach((p) => p.playing = false);
+    }
   }
   /** @private util function for handling error events from websocket */
   error(error) {
@@ -3628,6 +3847,16 @@ var NodeManager = class extends EventEmitter {
    * A map of all nodes in the nodeManager
    */
   nodes = new MiniMap();
+  /** @internal Coordinates player migrations between nodes owned by this manager. */
+  playerMigration = {
+    reservations: /* @__PURE__ */ new Map(),
+    capacityWaiters: /* @__PURE__ */ new Set()
+  };
+  /** @internal Wakes migrations waiting for capacity on one of this manager's nodes. */
+  signalPlayerMigrationCapacityChange() {
+    for (const resolve of this.playerMigration.capacityWaiters) resolve();
+    this.playerMigration.capacityWaiters.clear();
+  }
   /**
    * @param LavalinkManager The LavalinkManager that created this NodeManager
    */
@@ -6279,8 +6508,8 @@ var Player = class {
     try {
       if (!node)
         node = Array.from(this.LavalinkManager.nodeManager.leastUsedNodes("playingPlayers")).find(
-          (n) => n.connected && n.options.id !== this.node.options.id
-        ).id;
+          (n) => n.connected && !!n.sessionId && n.options.id !== this.node.options.id
+        )?.id;
       if (!node || !this.LavalinkManager.nodeManager.nodes.get(node))
         throw new RangeError("No nodes are available.");
       if (this.node.options.id === node) return this;
@@ -6435,6 +6664,11 @@ var LavalinkManager = class _LavalinkManager extends EventEmitter2 {
       advancedOptions: {
         enableDebugEvents: options?.advancedOptions?.enableDebugEvents ?? false,
         maxFilterFixDuration: options?.advancedOptions?.maxFilterFixDuration ?? 6e5,
+        playerMigration: {
+          concurrency: options?.advancedOptions?.playerMigration?.concurrency ?? 5,
+          perTargetConcurrency: options?.advancedOptions?.playerMigration?.perTargetConcurrency ?? 2,
+          backpressureDelayMs: options?.advancedOptions?.playerMigration?.backpressureDelayMs ?? 50
+        },
         debugOptions: {
           logCustomSearches: options?.advancedOptions?.debugOptions?.logCustomSearches ?? false,
           noAudio: options?.advancedOptions?.debugOptions?.noAudio ?? false,

package/dist/index.mjs

@@ -1204,6 +1204,11 @@ function safeStringify(obj, padding = 0) {
 }
 
 // src/structures/Node.ts
+var normalizeInt = (value, fallback, min, max) => {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(parsed)));
+};
 var LavalinkNode = class _LavalinkNode {
   heartBeatPingTimestamp = 0;
   heartBeatPongTimestamp = 0;
@@ -1638,7 +1643,12 @@ var LavalinkNode = class _LavalinkNode {
       { headers }
     );
     this.socket.on("open", this.open.bind(this));
-    this.socket.on("close", (code, reason) => this.close(code, reason?.toString()));
+    this.socket.on(
+      "close",
+      (code, reason) => void this.close(code, reason?.toString()).catch((error) => {
+        this.NodeManager.emit("error", this, error);
+      })
+    );
     this.socket.on("message", this.message.bind(this));
     this.socket.on("error", this.error.bind(this));
   }
@@ -1730,43 +1740,7 @@ var LavalinkNode = class _LavalinkNode {
           )
         );
       }
-      const nodeToMove = Array.from(this.NodeManager.leastUsedNodes("playingPlayers")).find(
-        (n) => n.connected && n.options.id !== this.id
-      );
-      if (!nodeToMove) {
-        return Promise.allSettled(
-          Array.from(players.values()).map(
-            (player) => player.destroy("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */).catch((error) => {
-              this._emitDebugEvent("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */, {
-                state: "error",
-                message: `Failed to destroy player ${player.guildId}: ${error.message}`,
-                error,
-                functionLayer: "Node > destroy() > movePlayers"
-              });
-            })
-          )
-        );
-      }
-      return Promise.allSettled(
-        Array.from(players.values()).map(
-          (player) => player.changeNode(nodeToMove.options.id).catch((error) => {
-            this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
-              state: "error",
-              message: `Failed to move player ${player.guildId}: ${error.message}`,
-              error,
-              functionLayer: "Node > destroy() > movePlayers"
-            });
-            return player.destroy(error.message ?? "PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
-              this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
-                state: "error",
-                message: `Failed to destroy player ${player.guildId} after move failure: ${destroyError.message}`,
-                error: destroyError,
-                functionLayer: "Node > destroy() > movePlayers"
-              });
-            });
-          })
-        )
-      );
+      return this.movePlayersToReplacementNode(Array.from(players.values()), "destroy");
     };
     return void handlePlayerOperations().finally(() => {
       this.socket?.close(1e3, "Node-Destroy");
@@ -1805,6 +1779,247 @@ var LavalinkNode = class _LavalinkNode {
     this.resetReconnectionAttempts();
     this.NodeManager.emit("disconnect", this, { code: 1e3, reason: disconnectReason });
   }
+  /**
+   * Pick the best ready node to move players to.
+   * A node must be connected and have a sessionId before a player can be migrated to it.
+   */
+  getReadyMigrationNode(excludeNodeId) {
+    return this.selectMigrationTarget(/* @__PURE__ */ new Set([excludeNodeId]), Number.MAX_SAFE_INTEGER);
+  }
+  getMigrationErrorMessage(error) {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "string") return error;
+    try {
+      return safeStringify(error);
+    } catch {
+      return String(error);
+    }
+  }
+  getMigrationConfig() {
+    const migration = this._LManager.options?.advancedOptions?.playerMigration;
+    return {
+      concurrency: normalizeInt(migration?.concurrency, 5, 1, 32),
+      perTargetConcurrency: normalizeInt(migration?.perTargetConcurrency, 2, 1, 8),
+      backpressureDelayMs: normalizeInt(migration?.backpressureDelayMs, 50, 0, 1e3)
+    };
+  }
+  getMigrationReservationCount(nodeId) {
+    return this.NodeManager.playerMigration.reservations.get(nodeId) || 0;
+  }
+  reserveMigrationTarget(nodeId) {
+    this.NodeManager.playerMigration.reservations.set(nodeId, this.getMigrationReservationCount(nodeId) + 1);
+  }
+  releaseMigrationTarget(nodeId) {
+    const current = this.getMigrationReservationCount(nodeId);
+    if (current <= 1) this.NodeManager.playerMigration.reservations.delete(nodeId);
+    else this.NodeManager.playerMigration.reservations.set(nodeId, current - 1);
+    this.NodeManager.signalPlayerMigrationCapacityChange();
+  }
+  getEffectiveMigrationLoad(node) {
+    return (node.stats?.players || 0) + this.getMigrationReservationCount(node.id);
+  }
+  selectMigrationTarget(excludeNodeIds, perTargetConcurrency) {
+    let selectedNode = null;
+    let selectedEffectiveLoad = Number.POSITIVE_INFINITY;
+    let selectedLiveLoad = Number.POSITIVE_INFINITY;
+    for (const node of this.NodeManager.nodes.values()) {
+      if (!node.connected || !node.sessionId) continue;
+      if (excludeNodeIds.has(node.id)) continue;
+      const reservationCount = this.getMigrationReservationCount(node.id);
+      if (reservationCount >= perTargetConcurrency) continue;
+      const liveLoad = node.stats?.players || 0;
+      const effectiveLoad = this.getEffectiveMigrationLoad(node);
+      if (!selectedNode || effectiveLoad < selectedEffectiveLoad || effectiveLoad === selectedEffectiveLoad && (liveLoad < selectedLiveLoad || liveLoad === selectedLiveLoad && node.id.localeCompare(selectedNode.id) < 0)) {
+        selectedNode = node;
+        selectedEffectiveLoad = effectiveLoad;
+        selectedLiveLoad = liveLoad;
+      }
+    }
+    return selectedNode;
+  }
+  hasAnyHealthyMigrationNode(excludeNodeIds) {
+    for (const node of this.NodeManager.nodes.values()) {
+      if (!node.connected || !node.sessionId) continue;
+      if (excludeNodeIds.has(node.id)) continue;
+      return true;
+    }
+    return false;
+  }
+  isMigrationNodeHealthy(nodeId) {
+    const node = this.NodeManager.nodes.get(nodeId);
+    return !!node?.connected && !!node.sessionId;
+  }
+  async waitForMigrationCapacity(excludeNodeIds, perTargetConcurrency, timeoutMs) {
+    if (this.selectMigrationTarget(excludeNodeIds, perTargetConcurrency)) return;
+    if (timeoutMs <= 0) {
+      await new Promise((resolve) => setImmediate(resolve));
+      return;
+    }
+    await new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const onSignal = () => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        this.NodeManager.playerMigration.capacityWaiters.delete(onSignal);
+        resolve();
+      };
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        this.NodeManager.playerMigration.capacityWaiters.delete(onSignal);
+        resolve();
+      }, timeoutMs);
+      this.NodeManager.playerMigration.capacityWaiters.add(onSignal);
+    });
+  }
+  /**
+   * Move a batch of players to a ready node with bounded concurrency.
+   * This keeps migration responsive without flooding the replacement node with requests.
+   */
+  async movePlayersToReplacementNode(players, onNoEligibleNode) {
+    const migrationQueue = players.filter((player) => {
+      if (player.getData("internal_nodeMigrating") === true) return false;
+      if (player.getData("internal_destroystatus") === true) return false;
+      player.setData("internal_nodeMigrating", true);
+      return true;
+    });
+    const { concurrency, perTargetConcurrency, backpressureDelayMs } = this.getMigrationConfig();
+    let nextQueueIndex = 0;
+    const workerCount = Math.min(concurrency, migrationQueue.length);
+    const migratePlayer = async (player) => {
+      const excludedNodes = /* @__PURE__ */ new Set();
+      try {
+        for (let attempt = 0; attempt < 2; attempt++) {
+          if (player.getData("internal_destroystatus") === true) return;
+          if (player.node?.options?.id !== this.id) return;
+          let targetNode = null;
+          while (!(targetNode = this.selectMigrationTarget(excludedNodes, perTargetConcurrency))) {
+            if (!this.hasAnyHealthyMigrationNode(excludedNodes)) {
+              this._emitDebugEvent("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */, {
+                state: "warn",
+                message: `No eligible ready node was available for player ${player.guildId}`,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (onNoEligibleNode === "destroy") {
+                await player.destroy("PlayerChangeNodeFailNoEligibleNode" /* PlayerChangeNodeFailNoEligibleNode */).catch((destroyError) => {
+                  this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+                    state: "error",
+                    message: `Failed to destroy player ${player.guildId}: ${this.getMigrationErrorMessage(destroyError)}`,
+                    error: destroyError,
+                    functionLayer: "Node > movePlayersToReplacementNode()"
+                  });
+                });
+              } else {
+                player.playing = false;
+              }
+              return;
+            }
+            await this.waitForMigrationCapacity(excludedNodes, perTargetConcurrency, backpressureDelayMs);
+          }
+          const targetNodeId = targetNode.id;
+          if (player.getData("internal_destroystatus") === true) return;
+          if (player.node?.options?.id !== this.id) return;
+          this.reserveMigrationTarget(targetNodeId);
+          try {
+            await player.changeNode(targetNodeId);
+            return;
+          } catch (error) {
+            const errorMessage = this.getMigrationErrorMessage(error);
+            this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+              state: "error",
+              message: `Failed to move player ${player.guildId}: ${errorMessage}`,
+              error,
+              functionLayer: "Node > movePlayersToReplacementNode()"
+            });
+            const targetStillHealthy = this.isMigrationNodeHealthy(targetNodeId);
+            excludedNodes.add(targetNodeId);
+            if (attempt === 0 && !targetStillHealthy) {
+              this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+                state: "warn",
+                message: `Migration target ${targetNodeId} became unavailable while moving player ${player.guildId}; retrying on another ready node`,
+                error,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (player.node?.options?.id === targetNodeId) player.node = this;
+              continue;
+            }
+            if (attempt === 0 && this.hasAnyHealthyMigrationNode(excludedNodes)) {
+              this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+                state: "warn",
+                message: `Retrying migration for player ${player.guildId} on a different ready node`,
+                error,
+                functionLayer: "Node > movePlayersToReplacementNode()"
+              });
+              if (player.node?.options?.id === targetNodeId) player.node = this;
+              continue;
+            }
+            if (onNoEligibleNode === "destroy") {
+              await player.destroy("PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
+                this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+                  state: "error",
+                  message: `Failed to destroy player ${player.guildId} after unexpected migration failure: ${this.getMigrationErrorMessage(destroyError)}`,
+                  error: destroyError,
+                  functionLayer: "Node > movePlayersToReplacementNode()"
+                });
+              });
+            } else {
+              player.playing = false;
+            }
+            return;
+          } finally {
+            this.releaseMigrationTarget(targetNodeId);
+          }
+        }
+      } catch (error) {
+        this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+          state: "error",
+          message: `Unexpected error while migrating player ${player.guildId}: ${this.getMigrationErrorMessage(error)}`,
+          error,
+          functionLayer: "Node > movePlayersToReplacementNode()"
+        });
+        if (onNoEligibleNode === "destroy") {
+          await player.destroy("PlayerChangeNodeFail" /* PlayerChangeNodeFail */).catch((destroyError) => {
+            this._emitDebugEvent("PlayerDestroyFail" /* PlayerDestroyFail */, {
+              state: "error",
+              message: `Failed to destroy player ${player.guildId} after unexpected migration failure: ${this.getMigrationErrorMessage(destroyError)}`,
+              error: destroyError,
+              functionLayer: "Node > movePlayersToReplacementNode()"
+            });
+          });
+        } else {
+          player.playing = false;
+        }
+      }
+    };
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (true) {
+        const queueIndex = nextQueueIndex++;
+        if (queueIndex >= migrationQueue.length) return;
+        const player = migrationQueue[queueIndex];
+        if (!player) continue;
+        try {
+          if (player.getData("internal_nodeMigrating") !== true) {
+            player.setData("internal_nodeMigrating", true);
+          }
+          if (player.getData("internal_destroystatus") === true) continue;
+          if (player.node?.options?.id !== this.id) continue;
+          await migratePlayer(player);
+        } catch (error) {
+          this._emitDebugEvent("PlayerChangeNodeFail" /* PlayerChangeNodeFail */, {
+            state: "error",
+            message: `Unexpected worker error while migrating player ${player.guildId}: ${this.getMigrationErrorMessage(error)}`,
+            error,
+            functionLayer: "Node > movePlayersToReplacementNode()"
+          });
+        } finally {
+          player.setData("internal_nodeMigrating", void 0);
+        }
+      }
+    });
+    await Promise.all(workers);
+  }
   /**
    * Gets all Players of a Node
    * @returns array of players inside of lavalink
@@ -2517,9 +2732,10 @@ var LavalinkNode = class _LavalinkNode {
     }
     this.info.isNodelink = !!this.info.isNodelink;
     this.NodeManager.emit("connect", this);
+    this.NodeManager.signalPlayerMigrationCapacityChange();
   }
   /** @private util function for handling closing events from websocket */
-  close(code, reason) {
+  async close(code, reason) {
     this.resetAckTimeouts(true, true);
     try {
       if (this.socket) {
@@ -2538,19 +2754,22 @@ var LavalinkNode = class _LavalinkNode {
     this.isAlive = false;
     if (code === 1006 && !reason) reason = "Socket got terminated due to no ping connection";
     if (code === 1e3 && reason === "Node-Disconnect") return;
+    const players = Array.from(
+      this._LManager.players.filter((p) => p?.node?.options?.id === this?.options?.id).values()
+    );
     this.NodeManager.emit("disconnect", this, { code, reason });
     if (code !== 1e3 || reason !== "Node-Destroy") {
       if (this.NodeManager.nodes.has(this.id)) {
         this.reconnect();
       }
     }
-    this._LManager.players.filter((p) => p?.node?.options?.id === this?.options?.id).forEach((p) => {
-      if (!this._LManager.options.autoMove) return p.playing = false;
-      if (this._LManager.options.autoMove) {
-        if (this.NodeManager.nodes.filter((n) => n.connected).size === 0) return p.playing = false;
-        p.moveNode();
-      }
-    });
+    if (this._LManager.options.autoMove && players.length) {
+      await this.movePlayersToReplacementNode(players, "freeze");
+    } else if (!this._LManager.options.autoMove) {
+      players.forEach((p) => p.playing = false);
+    } else if (this.NodeManager.nodes.filter((n) => n.connected && !!n.sessionId).size === 0) {
+      players.forEach((p) => p.playing = false);
+    }
   }
   /** @private util function for handling error events from websocket */
   error(error) {
@@ -3628,6 +3847,16 @@ var NodeManager = class extends EventEmitter {
    * A map of all nodes in the nodeManager
    */
   nodes = new MiniMap();
+  /** @internal Coordinates player migrations between nodes owned by this manager. */
+  playerMigration = {
+    reservations: /* @__PURE__ */ new Map(),
+    capacityWaiters: /* @__PURE__ */ new Set()
+  };
+  /** @internal Wakes migrations waiting for capacity on one of this manager's nodes. */
+  signalPlayerMigrationCapacityChange() {
+    for (const resolve of this.playerMigration.capacityWaiters) resolve();
+    this.playerMigration.capacityWaiters.clear();
+  }
   /**
    * @param LavalinkManager The LavalinkManager that created this NodeManager
    */
@@ -6279,8 +6508,8 @@ var Player = class {
     try {
       if (!node)
         node = Array.from(this.LavalinkManager.nodeManager.leastUsedNodes("playingPlayers")).find(
-          (n) => n.connected && n.options.id !== this.node.options.id
-        ).id;
+          (n) => n.connected && !!n.sessionId && n.options.id !== this.node.options.id
+        )?.id;
       if (!node || !this.LavalinkManager.nodeManager.nodes.get(node))
         throw new RangeError("No nodes are available.");
       if (this.node.options.id === node) return this;
@@ -6435,6 +6664,11 @@ var LavalinkManager = class _LavalinkManager extends EventEmitter2 {
       advancedOptions: {
         enableDebugEvents: options?.advancedOptions?.enableDebugEvents ?? false,
         maxFilterFixDuration: options?.advancedOptions?.maxFilterFixDuration ?? 6e5,
+        playerMigration: {
+          concurrency: options?.advancedOptions?.playerMigration?.concurrency ?? 5,
+          perTargetConcurrency: options?.advancedOptions?.playerMigration?.perTargetConcurrency ?? 2,
+          backpressureDelayMs: options?.advancedOptions?.playerMigration?.backpressureDelayMs ?? 50
+        },
         debugOptions: {
           logCustomSearches: options?.advancedOptions?.debugOptions?.logCustomSearches ?? false,
           noAudio: options?.advancedOptions?.debugOptions?.noAudio ?? false,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lavalink-client",
-    "version": "2.10.3",
+    "version": "2.10.4",
     "description": "Easy, flexible and feature-rich lavalink@v4 Client. Both for Beginners and Proficients. - Supports NodeLink@v3 too.",
     "keywords": [
         "advanced",