{"record":{"id":"e5027e90f490ce57","repo":"heygen-com/hyperframes","slug":"no-studio-preview-server-for-this-project-is-runni","errorCode":null,"errorMessage":"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\" : \"\"}.","messagePattern":"No Studio preview server for this project is running on port (.+?)\\. Matching server port(.+?): (.+?)\\. Rerun with --port (.+?)(.+?)\\.","errorType":"exception","errorClass":"PreviewServerPortMismatchError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/utils/studioSelectionClient.ts","lineNumber":82,"sourceCode":"  startPort = 3002,\n  scan: (startPort?: number) => Promise<ActiveServer[]> = scanActiveServers,\n  fetchImpl: typeof fetch = fetch,\n  options: FindPreviewServerOptions = {},\n): Promise<ActiveServer | null> {\n  const normalizedProjectDir = normalizePath(projectDir);\n  const servers = await scan(startPort);\n  const embeddedServers = servers.filter(\n    (server) => normalizePath(server.projectDir) === normalizedProjectDir,\n  );\n  if (options.preferredPort !== undefined) {\n    const preferred = embeddedServers.find((server) => server.port === options.preferredPort);\n    if (preferred) return preferred;\n    const viteServer = await findViteStudioServerForProject(normalizedProjectDir, fetchImpl, [\n      options.preferredPort,\n    ]);\n    if (viteServer) return viteServer;\n    if (embeddedServers.length > 0) {\n      throw new PreviewServerPortMismatchError(options.preferredPort, embeddedServers);\n    }\n    return null;\n  }\n  if (embeddedServers.length === 1) return embeddedServers[0]!;\n  if (embeddedServers.length > 1) throw new AmbiguousPreviewServerError(embeddedServers);\n  return findViteStudioServerForProject(normalizedProjectDir, fetchImpl);\n}\n\nexport function studioSelectionUrl(server: ActiveServer): string {\n  return studioApiUrl(server, \"selection\");\n}\n\nexport function studioApiUrl(server: ActiveServer, route: string): string {\n  const host = server.host ?? \"127.0.0.1\";\n  return `http://${host}:${server.port}/api/projects/${encodeURIComponent(server.projectName)}/${route}`;\n}\n\n// Vite dev servers bind IPv6 loopback (`::1`) by default while embedded servers","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/utils/studioSelectionClient.ts#L64-L100","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: hyperframes lint --port 3003\n// after:  hyperframes lint --port 3002  (the port listed in the error)","handlingStrategy":"validation","validationCode":"import { PreviewServerPortMismatchError } from \"./studioSelectionClient.js\";\n\n// After catching the error, read .ports to find the correct server\nfunction suggestCorrectPort(err: PreviewServerPortMismatchError): number {\n  return err.ports[0];\n}","typeGuard":"function isPreviewServerPortMismatch(err: unknown): err is PreviewServerPortMismatchError {\n  return err instanceof PreviewServerPortMismatchError;\n}","tryCatchPattern":"try {\n  const server = await findPreviewServerForProject(dir, startPort, scan, fetch, { preferredPort });\n} catch (err) {\n  if (err instanceof PreviewServerPortMismatchError) {\n    // Auto-correct: retry with the first suggested port\n    const corrected = await findPreviewServerForProject(dir, startPort, scan, fetch, {\n      preferredPort: err.ports[0],\n    });\n  } else throw err;\n}","preventionTips":["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."],"tags":["studio","preview-server","port","cli"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}