pbakaus/impeccable · error · Error

TanStack Start live adapter requires a numeric port

Error message

TanStack Start live adapter requires a numeric port

What it means

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.

Source

Thrown at plugin/skills/impeccable/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

1. Pass a numeric port: applyTanStackLiveAdapter({ cwd, port: 3000, token }).
2. Parse and validate the port upstream before invoking the adapter.
3. Confirm the boot flow defaults a port when none is provided.

Example fix

// before
applyTanStackLiveAdapter({ cwd, port: process.env.PORT, token });

// after
const port = Number(process.env.PORT);
if (!Number.isFinite(port)) throw new Error('PORT must be numeric');
applyTanStackLiveAdapter({ cwd, port, token });

function isValidPort(port) {
  const n = Number(port);
  return Number.isFinite(n) && n > 0 && n < 65536;
}

function isNumericPort(port) {
  return Number.isFinite(Number(port));
}

try {
  applyTanStackLiveAdapter({ cwd, port, token });
} catch (err) {
  if (err.message === 'TanStack Start live adapter requires a numeric port') {
    port = 3000;
    applyTanStackLiveAdapter({ cwd, port, token });
  } else throw err;
}

When it happens

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

Common situations: Boot flow failed to resolve a port, env var missing, or a caller passing the raw argv string without parsing.

Related errors

• SvelteKit live adapter requires a numeric port
• TanStack Start live adapter requires a numeric port
• --target requires a path value (use --target <path> or --tar
• SvelteKit live adapter requires a numeric port
• invalid catalog: ${validation.errors.join('; ')}

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