메뉴
Known bugs and root causes encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
How the multi-backend adapter system works — AgentAdapter interface, ACP protocol, session resume, and how to add new provider adapters
When debugging why an agent has the wrong provider/model, or when modifying agent creation or delegation flows.
How to get agents to use group chats for peer coordination in flightdeck-based crews. Covers hub-and-spoke anti-pattern, auto-grouping triggers, and file-lock-linked groups. Use when setting up multi-agent crews with 3+ agents or diagnosing why agents aren't collaborating directly.
When fetching from the `/coordination/activity` API and you only need specific action types (e.g., `progress_update`, `task_completed`, `delegated`).
When fetching activity data for UI display, or debugging why activity-based features show empty/stale data.
Architecture decisions and patterns from Flightdeck development (Phases 2–4). Covers feature architecture, state management, component patterns, and API design.
| 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. |
Bugs encountered during Flightdeck development. Check this list before debugging — you may be hitting a known issue.
/api/ PrefixSymptom: 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.
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.
Symptom: Overview page shows blank panels despite data existing. Cause: Multiple possible issues:
SessionReplay.ts KEYFRAME_TYPES must map activity actionType to keyframe type.leadId vs projectId confusion — some APIs filter by one, frontend passes the other.'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.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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.