fix(server-core): report occupied initial port

Author: omeraplak

.changeset/port-conflict-guidance.md

@@ -0,0 +1,7 @@
+---
+"@voltagent/server-core": patch
+---
+
+fix(server-core): report initial port conflicts instead of silently switching ports
+
+When the requested or default port is already in use, VoltAgent now stops with guidance for configuring a different port instead of automatically binding to another available port. This includes the `honoServer()` default path: calling `honoServer()` without a port now fails fast if the default `3141` port is occupied, and users can opt into another port with `honoServer({ port: 4310 })`.

packages/server-core/src/utils/port-manager.spec.ts

@@ -106,13 +106,12 @@ describe("PortManager", () => {
         }
       });
 
-      // Try to allocate again - should get next port
-      const port2 = await portManager.allocatePort(3141);
-      expect(port2).not.toBe(3141);
-      expect(port2).toBe(4310); // Next preferred port
+      await expect(portManager.allocatePort(3141)).rejects.toThrow(
+        "Port 3141 is already in use. To use another port, pass it to your server config, for example: honoServer({ port: 4310 })",
+      );
     });
 
-    it("should handle port in use (EADDRINUSE)", async () => {
+    it("should throw with guidance when preferred port is in use (EADDRINUSE)", async () => {
       let portBeingTested: number | undefined;
 
       (createNetServer as any).mockImplementation(() => {
@@ -145,9 +144,44 @@ describe("PortManager", () => {
         return mockServer;
       });
 
-      const port = await portManager.allocatePort(3141);
-      expect(port).not.toBe(3141);
-      expect(port).toBe(4310); // Should try next port after skipping duplicate 3141
+      await expect(portManager.allocatePort(3141)).rejects.toThrow(
+        "Port 3141 is already in use. To use another port, pass it to your server config, for example: honoServer({ port: 4310 })",
+      );
+    });
+
+    it("should throw with guidance when default port is in use", async () => {
+      let portBeingTested: number | undefined;
+
+      (createNetServer as any).mockImplementation(() => {
+        const mockServer = {
+          once: vi.fn(),
+          listen: vi.fn((port: number) => {
+            portBeingTested = port;
+          }),
+          close: vi.fn((callback?: () => void) => callback?.()),
+        };
+
+        const handlers: Record<string, (...args: any[]) => void> = {};
+        mockServer.once.mockImplementation((event: string, handler: (...args: any[]) => void) => {
+          handlers[event] = handler;
+          if (Object.keys(handlers).length === 2) {
+            setTimeout(() => {
+              if (portBeingTested === 3141) {
+                handlers.error({ code: "EADDRINUSE" });
+              } else {
+                handlers.listening();
+              }
+            }, 0);
+          }
+          return mockServer;
+        });
+
+        return mockServer;
+      });
+
+      await expect(portManager.allocatePort()).rejects.toThrow(
+        "Port 3141 is already in use. To use another port, pass it to your server config, for example: honoServer({ port: 4310 })",
+      );
     });
 
     it("should handle permission denied (EACCES)", async () => {
@@ -183,9 +217,9 @@ describe("PortManager", () => {
         return mockServer;
       });
 
-      const port = await portManager.allocatePort(80); // Low port, likely EACCES
-      expect(port).not.toBe(80);
-      expect(port).toBe(3141); // Should try next port
+      await expect(portManager.allocatePort(80)).rejects.toThrow(
+        "Port 80 is already in use. To use another port, pass it to your server config, for example: honoServer({ port: 3141 })",
+      );
     });
 
     it("should throw error when no ports are available", async () => {
@@ -202,10 +236,12 @@ describe("PortManager", () => {
         getPortsToTry: originalGetPortsToTry,
       }));
 
-      await expect(portManager.allocatePort()).rejects.toThrow("Could not find an available port");
+      await expect(portManager.allocatePort()).rejects.toThrow(
+        "Port 3141 is already in use and no alternative port is available",
+      );
     });
 
-    it("should handle concurrent allocation requests", async () => {
+    it("should reject concurrent default allocation requests after the first allocation", async () => {
       // Create multiple mock servers for concurrent allocation
       (createNetServer as any).mockImplementation(() => {
         const newMockServer = {
@@ -226,21 +262,28 @@ describe("PortManager", () => {
       });
 
       // Start multiple allocations concurrently
-      const promises = [
+      const results = await Promise.allSettled([
         portManager.allocatePort(),
         portManager.allocatePort(),
         portManager.allocatePort(),
-      ];
+      ]);
 
-      const results = await Promise.all(promises);
+      const fulfilled = results.filter((result) => result.status === "fulfilled");
+      const rejected = results.filter((result) => result.status === "rejected");
 
-      // All ports should be different
-      expect(new Set(results).size).toBe(3);
+      expect(fulfilled).toHaveLength(1);
+      expect(rejected).toHaveLength(2);
+      expect(fulfilled[0]).toMatchObject({ value: 3141 });
 
-      // All ports should be allocated
-      results.forEach((port) => {
-        expect(portManager.isPortAllocated(port)).toBe(true);
+      rejected.forEach((result) => {
+        expect(result.reason).toBeInstanceOf(Error);
+        expect((result.reason as Error).message).toMatch(
+          /^Port 3141 is already in use\. To use another port, pass it to your server config, for example: honoServer\(\{ port: \d+ \}\)$/,
+        );
       });
+
+      expect(portManager.isPortAllocated(3141)).toBe(true);
+      expect(portManager.isPortAllocated(4310)).toBe(false);
     });
 
     it("should wait for existing port check to complete", async () => {
@@ -269,12 +312,13 @@ describe("PortManager", () => {
       await delay(10); // Small delay to ensure first check is in progress
       const promise2 = portManager.allocatePort(5000);
 
-      const [port1, port2] = await Promise.all([promise1, promise2]);
+      const port1 = await promise1;
+      await expect(promise2).rejects.toThrow(
+        "Port 5000 is already in use. To use another port, pass it to your server config, for example: honoServer({ port: 3141 })",
+      );
 
       // First should get the requested port
       expect(port1).toBe(5000);
-      // Second should get a different port (since first is checking/allocated)
-      expect(port2).not.toBe(5000);
       expect(checkCompleted).toBe(true);
     });
   });
@@ -443,9 +487,9 @@ describe("PortManager", () => {
         return mockServer;
       });
 
-      const port = await portManager.allocatePort(3000);
-      expect(port).not.toBe(3000);
-      expect(port).toBe(3141); // Should try the first preferred port
+      await expect(portManager.allocatePort(3000)).rejects.toThrow(
+        "Port 3000 is already in use. To use another port, pass it to your server config, for example: honoServer({ port: 3141 })",
+      );
     });
 
     it("should cleanup promises map even on error", async () => {

packages/server-core/src/utils/port-manager.ts

@@ -85,22 +85,49 @@ class PortManager {
    */
   public async allocatePort(preferredPort?: number): Promise<number> {
     const portsToTry = getPortsToTry(preferredPort);
+    const initialPort = portsToTry[0];
+
+    if (!this.allocatedPorts.has(initialPort)) {
+      const isAvailable = await this.isPortAvailable(initialPort);
+      if (isAvailable) {
+        this.allocatedPorts.add(initialPort);
+        return initialPort;
+      }
+    }
+
+    const alternativePort = await this.findAvailableAlternativePort(initialPort, portsToTry);
+    throw new Error(this.createPortInUseMessage(initialPort, alternativePort));
+  }
+
+  private async findAvailableAlternativePort(
+    unavailablePort: number,
+    portsToTry: number[],
+  ): Promise<number> {
+    const seenPorts = new Set<number>([unavailablePort]);
 
     for (const port of portsToTry) {
-      // Skip if already allocated
-      if (this.allocatedPorts.has(port)) {
+      if (seenPorts.has(port) || this.allocatedPorts.has(port)) {
         continue;
       }
 
+      seenPorts.add(port);
+
       const isAvailable = await this.isPortAvailable(port);
       if (isAvailable) {
-        // Reserve this port
-        this.allocatedPorts.add(port);
         return port;
       }
     }
 
-    throw new Error("Could not find an available port");
+    throw new Error(
+      `Port ${unavailablePort} is already in use and no alternative port is available`,
+    );
+  }
+
+  private createPortInUseMessage(unavailablePort: number, alternativePort: number): string {
+    return [
+      `Port ${unavailablePort} is already in use.`,
+      `To use another port, pass it to your server config, for example: honoServer({ port: ${alternativePort} })`,
+    ].join(" ");
   }
 
   /**