{"record":{"id":"3fa4ffe8fd4eccd2","repo":"pbakaus/impeccable","slug":"tanstack-start-live-adapter-requires-a-numeric-por","errorCode":null,"errorMessage":"TanStack Start live adapter requires a numeric port","messagePattern":"TanStack Start live adapter requires a numeric port","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugin/skills/impeccable/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/plugin/skills/impeccable/scripts/live/tanstack-adapter.mjs#L42-L78","documentation":"Thrown by applyTanStackLiveAdapter when the port argument is not coercible to a finite number. Identical rationale to the SvelteKit adapter: the mount component embeds the port, so a bad value is rejected before any file is written.","triggerScenarios":"Calling applyTanStackLiveAdapter({ port: undefined }) or a non-numeric port value. The check runs after the tanstack_not_detected early return, so the project must already be detected.","commonSituations":"Boot flow failed to resolve a port, env var missing, or a caller passing the raw argv string without parsing.","solutions":["Pass a numeric port: applyTanStackLiveAdapter({ cwd, port: 3000, token }).","Parse and validate the port upstream before invoking the adapter.","Confirm the boot flow defaults a port when none is provided."],"exampleFix":"// before\napplyTanStackLiveAdapter({ cwd, port: process.env.PORT, token });\n\n// after\nconst port = Number(process.env.PORT);\nif (!Number.isFinite(port)) throw new Error('PORT must be numeric');\napplyTanStackLiveAdapter({ cwd, port, token });","handlingStrategy":"validation","validationCode":"function isValidPort(port) {\n  const n = Number(port);\n  return Number.isFinite(n) && n > 0 && n < 65536;\n}","typeGuard":"function isNumericPort(port) {\n  return Number.isFinite(Number(port));\n}","tryCatchPattern":"try {\n  applyTanStackLiveAdapter({ cwd, port, token });\n} catch (err) {\n  if (err.message === 'TanStack Start live adapter requires a numeric port') {\n    port = 3000;\n    applyTanStackLiveAdapter({ cwd, port, token });\n  } else throw err;\n}","preventionTips":["Parse and validate the port once at boot and reuse the numeric value.","Refuse to call the adapter when the port is unset rather than passing undefined.","Share a single port-validation helper across both adapters."],"tags":["validation","tanstack","impeccable-live","port"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}