{"record":{"id":"471489cd3e6401e6","repo":"pbakaus/impeccable","slug":"tanstack-start-live-adapter-requires-a-numeric-por-471489","errorCode":null,"errorMessage":"TanStack Start live adapter requires a numeric port","messagePattern":"TanStack Start live adapter requires a numeric port","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"skill/scripts/live/tanstack-adapter.mjs","lineNumber":60,"sourceCode":"];\n\nexport function detectTanStackStartProject(cwd = process.cwd()) {\n  if (!packageHasTanStackStart(cwd)) return null;\n  const rootRoute = findRootRouteFile(cwd);\n  if (!rootRoute) return null;\n\n  const ext = path.extname(rootRoute);\n  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';\n  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;\n  const componentImport = relativeImportSpecifier(rootRoute, componentFile);\n\n  return { rootRoute, componentFile, componentImport, ext };\n}\n\nexport function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {\n  if (!project) return { error: 'tanstack_not_detected' };\n  if (!Number.isFinite(Number(port))) {\n    throw new Error('TanStack Start live adapter requires a numeric port');\n  }\n\n  // Write the managed mount component.\n  const componentAbs = path.join(cwd, project.componentFile);\n  const componentBody = buildTanStackLiveRootComponent(Number(port), token);\n  const componentExisted = fs.existsSync(componentAbs);\n  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {\n    // A non-Impeccable file already sits at our managed path — refuse to clobber.\n    return {\n      file: project.componentFile,\n      error: 'tanstack_component_conflict',\n      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,\n    };\n  }\n  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });\n  fs.writeFileSync(componentAbs, componentBody, 'utf-8');\n\n  // Patch the root document to import + render the mount component.","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/pbakaus/impeccable/blob/d14711ae3d1a1dd62dee61a358d27f107c51ccd0/skill/scripts/live/tanstack-adapter.mjs#L42-L78","documentation":"Thrown by applyTanStackLiveAdapter() in live/tanstack-adapter.mjs when 'port' fails Number.isFinite(Number(port)). Same contract as the SvelteKit adapter: a numeric port must be embedded into the managed TanStack live root component. The guard runs after the project-detection early return (so a missing project returns {error:'tanstack_not_detected'} instead) but before writing the managed component, so no files are mutated on a bad port.","triggerScenarios":"applyTanStackLiveAdapter({cwd, port, token, project}) is called with port = undefined, null, NaN, Infinity, or a non-numeric string. Note the project arg defaults to detectTanStackStartProject(cwd); if that returns null the function returns {error:'tanstack_not_detected'} and never reaches the port guard.","commonSituations":"Port sourced from an unset env var; CLI parsing left port as undefined when the flag was omitted; caller passed a host:port string by mistake; a refactor removed the default port constant.","solutions":["Pass a finite number: applyTanStackLiveAdapter({cwd, port: 4321, token}).","Coerce from env with a fallback and a finite check: const port = Number(process.env.PORT || 4321).","Confirm project detection succeeded first (else you get tanstack_not_detected, not this error)."],"exampleFix":"// before\napplyTanStackLiveAdapter({ cwd, port: process.env.PORT, token })\n// after\nconst port = Number(process.env.PORT || 4321)\napplyTanStackLiveAdapter({ cwd, port, token })","handlingStrategy":"validation","validationCode":"const portNum = Number(port);\nif (!Number.isFinite(portNum)) throw new Error('port must be a finite number');\napplyTanStackLiveAdapter({ cwd, port: portNum, token });","typeGuard":"function isFinitePort(v: unknown): v is number {\n  return Number.isFinite(typeof v === 'number' ? v : Number(v));\n}","tryCatchPattern":null,"preventionTips":["Detect the project first; only pass a port when detection succeeds.","Resolve the port from a single env-aware helper reused by both SvelteKit and TanStack adapters.","Default the port explicitly rather than letting undefined propagate."],"tags":["tanstack","adapter","port","validation","live"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}