What causes "TanStack Start live adapter requires a numeric port" in pbakaus/impeccable?

TanStack Start live adapter requires a numeric port

Error message

TanStack Start live adapter requires a numeric port

What it means

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.

Source

Thrown at skill/scripts/live/tanstack-adapter.mjs:60

];

export function detectTanStackStartProject(cwd = process.cwd()) {
  if (!packageHasTanStackStart(cwd)) return null;
  const rootRoute = findRootRouteFile(cwd);
  if (!rootRoute) return null;

  const ext = path.extname(rootRoute);
  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
  const componentImport = relativeImportSpecifier(rootRoute, componentFile);

  return { rootRoute, componentFile, componentImport, ext };
}

export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
  if (!project) return { error: 'tanstack_not_detected' };
  if (!Number.isFinite(Number(port))) {
    throw new Error('TanStack Start live adapter requires a numeric port');
  }

  // Write the managed mount component.
  const componentAbs = path.join(cwd, project.componentFile);
  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
  const componentExisted = fs.existsSync(componentAbs);
  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
    // A non-Impeccable file already sits at our managed path — refuse to clobber.
    return {
      file: project.componentFile,
      error: 'tanstack_component_conflict',
      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
    };
  }
  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
  fs.writeFileSync(componentAbs, componentBody, 'utf-8');

  // Patch the root document to import + render the mount component.

View on GitHub (pinned to d14711ae3d)

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).

Example fix

// before
applyTanStackLiveAdapter({ cwd, port: process.env.PORT, token })
// after
const port = Number(process.env.PORT || 4321)
applyTanStackLiveAdapter({ cwd, port, token })

Defensive patterns

Strategy: validation

Validate before calling

const portNum = Number(port);
if (!Number.isFinite(portNum)) throw new Error('port must be a finite number');
applyTanStackLiveAdapter({ cwd, port: portNum, token });

Type guard

function isFinitePort(v: unknown): v is number {
  return Number.isFinite(typeof v === 'number' ? v : Number(v));
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/471489cd3e6401e6. Report an issue: GitHub.