common-bugs

name	common-bugs
description	Known bugs and root causes encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.

Common Bugs and Root Causes

Bugs encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.

Double /api/ Prefix

Symptom: API calls return HTML instead of JSON, 404 errors. Cause: apiFetch() already prepends /api. Writing apiFetch('/api/projects') produces /api/api/projects. Fix: Use apiFetch('/projects') — no /api prefix.

Infinite Re-fetch Loops

Symptom: Network tab shows hundreds of identical requests, browser freezes. Cause: Putting setState return value or fetched data in useCallback/useEffect dependency arrays creates a render → fetch → setState → render cycle. Fix: Use refs for mutable values that shouldn't trigger re-renders, or move fetch logic into the effect body.

Overview Panels Empty

Symptom: Overview page shows blank panels despite data existing. Cause: Multiple possible issues:

• Keyframe type mappings missing — SessionReplay.ts KEYFRAME_TYPES must map activity actionType to keyframe type.
• leadId vs projectId confusion — some APIs filter by one, frontend passes the other.
• Spawn detection relies on 'Created &' prefix in activity label — if format changes, agents aren't detected. Fix: Check KEYFRAME_TYPES mapping, verify API query parameters, check activity label format.

FocusPanel Crash on Nested Objects

Symptom: TypeError when rendering agent details or activity data. Cause: API returns nested objects (e.g., { status: { phase: "running" } }), but component expects strings. Fix: Use a safeText() helper: typeof val === 'object' ? JSON.stringify(val) : String(val).

SVG Text Invisible in Dark Theme

Symptom: Chart axis labels, tick marks disappear on dark background. Cause: SVG <text> ignores CSS classes and CSS variables. Default fill is black (#000), invisible on dark bg. Fix: Pass fill="#9ca3af" directly via tickLabelProps or inline style. Never rely on Tailwind/CSS for SVG text color.

Full Page Refresh on Navigation

Symptom: Clicking a link reloads the entire app, losing state. Cause: Using <a href="/path"> instead of React Router <Link to="/path">. Fix: Replace all internal <a href> with <Link to> from react-router-dom.

Components Invisible (Overflow Clipping)

Symptom: Component exists in DOM (visible in DevTools) but not visible on screen. Cause: Parent container has overflow: hidden and the component renders below the visible area. Fix: Either move the component outside the clipped container, make it position: sticky, or change overflow: hidden to overflow: auto.

Passive Event Listener Warnings

Symptom: Console warning about passive event listeners on wheel events. Cause: Calling preventDefault() on wheel events added without { passive: false }. Fix: Add wheel listeners via addEventListener('wheel', handler, { passive: false }) instead of React's onWheel.

Server Port Mismatch

Symptom: API calls fail, CORS errors, connection refused. Cause: Server port comes from SERVER_PORT env (currently 3006). Vite proxies from :5173. Fix: Check SERVER_PORT env var. In dev, always use Vite's port (5173) — it proxies to the server.

Duplicate Variable Declarations

Symptom: TypeScript error "Cannot redeclare block-scoped variable". Cause: Multiple developers editing the same file, each adding their own const declarations. Fix: Check for existing declarations before adding. Use file locking to prevent concurrent edits.

Scroll Axes Coupled

Symptom: Vertical mouse wheel causes horizontal movement on Timeline. Cause: wheel handler using deltaY for horizontal panning. Fix: deltaY → vertical only (let browser handle), deltaX / Shift+wheel → horizontal pan, Ctrl+wheel → zoom.

Token Data "Not Available"

Symptom: Token tab shows "not available" for agents. Cause: Agent objects lack inputTokens/outputTokens (Copilot CLI doesn't provide them). Fix: Estimate from outputPreview length (~4 chars/token). Show with ~ prefix and (est.) suffix.

Overflow:Hidden Clipping Below-Fold Components

Symptom: Component exists in DOM (DevTools shows it) but user can't see or interact with it. Cause: Parent container has overflow: hidden and the component renders below the visible area. Example: ReplayScrubber rendered after a 1000px Gantt chart inside a 713px container. Fix: Move the component outside the scrollable container as a sibling with shrink-0. Or use position: sticky; bottom: 0 to pin it.

CDN Fonts Break Offline

Symptom: Monospace text falls back to system font when offline or in restricted networks. Cause: Font loaded via Google Fonts CDN <link> tag — requires network. Fix: Always bundle fonts locally. Download woff2 files → public/fonts/ → @font-face in CSS. Remove any CDN <link> and preconnect tags from index.html.

react-virtuoso Elements Not in DOM

Symptom: Tests or Playwright can't find elements that should be in a list. Cause: react-virtuoso only renders visible items. Off-screen items are virtualized away and not in the DOM. Fix: In tests, mock Virtuoso to render all items. In production, use Virtuoso's scrollToIndex API to bring items into view.

Virtuoso Inline Header/Footer Cause Remounts

Symptom: Header or footer components inside Virtuoso flicker, lose state, or remount on every scroll. Cause: Passing inline component definitions to components={{ Header: () => <div>...</div> }} creates new component references on every render. Fix: Extract Header/Footer to stable refs or define them outside the render function.

Backend Pre-Truncating Labels

Symptom: Milestone or keyframe labels cut off even though frontend has room. Cause: Backend applies .slice(0, 80) to labels before sending to frontend. Fix: Remove backend truncation. Let the frontend handle display with CSS (line-clamp-2, title tooltip).

Playwright Can't Simulate Complex Events on SVG

Symptom: QA automation can't test Ctrl+wheel zoom, keyboard nav, or drag on SVG chart elements. Cause: Playwright's keyboard/mouse simulation doesn't reliably trigger React synthetic events on SVG elements, especially with modifier keys. Fix: Write unit tests with fireEvent.wheel/fireEvent.keyDown from @testing-library/react for interaction logic. Use Playwright only for visual/screenshot verification.