heygen-com/hyperframes · error · PreviewServerPortMismatchError

No Studio preview server for this project is running on port

Error message

No Studio preview server for this project is running on port ${requestedPort}. Matching server port${ports.length === 1 ? "" : "s"}: ${ports.join(", ")}. Rerun with --port ${ports[0]}${ports.length > 1 ? " or omit --port to see all candidates" : ""}.

What it means

Thrown as PreviewServerPortMismatchError when the user specifies --port N but no Studio preview server for their project is running on that port, while matching servers exist on other ports. The error lists the actual ports and suggests rerunning with the correct --port value. This only fires when embeddedServers is non-empty (at least one server for this project exists, just not on the requested port).

Source

Thrown at packages/cli/src/utils/studioSelectionClient.ts:82

  startPort = 3002,
  scan: (startPort?: number) => Promise<ActiveServer[]> = scanActiveServers,
  fetchImpl: typeof fetch = fetch,
  options: FindPreviewServerOptions = {},
): Promise<ActiveServer | null> {
  const normalizedProjectDir = normalizePath(projectDir);
  const servers = await scan(startPort);
  const embeddedServers = servers.filter(
    (server) => normalizePath(server.projectDir) === normalizedProjectDir,
  );
  if (options.preferredPort !== undefined) {
    const preferred = embeddedServers.find((server) => server.port === options.preferredPort);
    if (preferred) return preferred;
    const viteServer = await findViteStudioServerForProject(normalizedProjectDir, fetchImpl, [
      options.preferredPort,
    ]);
    if (viteServer) return viteServer;
    if (embeddedServers.length > 0) {
      throw new PreviewServerPortMismatchError(options.preferredPort, embeddedServers);
    }
    return null;
  }
  if (embeddedServers.length === 1) return embeddedServers[0]!;
  if (embeddedServers.length > 1) throw new AmbiguousPreviewServerError(embeddedServers);
  return findViteStudioServerForProject(normalizedProjectDir, fetchImpl);
}

export function studioSelectionUrl(server: ActiveServer): string {
  return studioApiUrl(server, "selection");
}

export function studioApiUrl(server: ActiveServer, route: string): string {
  const host = server.host ?? "127.0.0.1";
  return `http://${host}:${server.port}/api/projects/${encodeURIComponent(server.projectName)}/${route}`;
}

// Vite dev servers bind IPv6 loopback (`::1`) by default while embedded servers

View on GitHub (pinned to c2996c8626)

Solutions

Rerun with the port suggested in the error message (e.g. --port 3002).
Omit --port entirely to let the CLI auto-discover the correct server.
Check which ports are in use with the error's listed ports and close stale servers.
Restart the Studio preview server and note the port it reports.

Example fix

// before: hyperframes lint --port 3003
// after:  hyperframes lint --port 3002  (the port listed in the error)

Defensive patterns

Strategy: validation

Validate before calling

import { PreviewServerPortMismatchError } from "./studioSelectionClient.js";

// After catching the error, read .ports to find the correct server
function suggestCorrectPort(err: PreviewServerPortMismatchError): number {
  return err.ports[0];
}

Type guard

function isPreviewServerPortMismatch(err: unknown): err is PreviewServerPortMismatchError {
  return err instanceof PreviewServerPortMismatchError;
}

Try / catch

try {
  const server = await findPreviewServerForProject(dir, startPort, scan, fetch, { preferredPort });
} catch (err) {
  if (err instanceof PreviewServerPortMismatchError) {
    // Auto-correct: retry with the first suggested port
    const corrected = await findPreviewServerForProject(dir, startPort, scan, fetch, {
      preferredPort: err.ports[0],
    });
  } else throw err;
}

Prevention

Omit --port unless you have a specific reason to pin it — auto-discovery handles single-server cases.
Note the port Studio reports when it starts, and use that value if pinning.
Close stale preview servers to reduce port confusion.

When it happens

Trigger: User runs a CLI command with --port 3003 but the project's preview server is on 3002; multiple projects are running and the user picked the wrong port; the server restarted on a different port after the user noted the original.

Common situations: Default port 3002 was taken so Studio auto-incremented to 3003; user has multiple HyperFrames projects open with preview servers on different ports; stale --port value from a previous session.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/e5027e90f490ce57. Report an issue: GitHub.