debugging-log

FaceKom Debugging Log

Purpose

Past bugs, their root causes, and resolutions. Reference for avoiding repeat issues.

vuer_oss Crash Loop - Missing Model Module (March 2026)

Ticket: FKITDEV-7855 Branch: feature/FKITDEV-7855 Symptom: vuer_oss enters crash loop on startup, Supervisor rapidly cycles PIDs (4874→4893→4912→4931)

Root Cause Chain

1. Missing model file: server/db/model/room (and callbackrequest) not found

   • Error: ERR_MODULE_NOT_FOUND at /workspace/vuer_oss/server/db/model/room
   • Imported from server/db/models.ts
   • Each restart attempt fails within 1-2 seconds, exit code 2

2. TypeScript/JavaScript module mismatch:

   • server/db/models.ts uses ESM import statements (60+)
   • Same file exports via CJS module.exports = (sequelize) => {...}
   • No "type": "module" in package.json → Node.js treats as CommonJS
   • No TypeScript runtime tooling (ts-node/tsx/@swc) installed

3. Extension resolution across codebase:

   • server/bootstrap/connection/db.js (JS!) requires ../../db/models.ts with explicit .ts
   • All 38 require() calls use explicit .ts extension
   • Node.js needs --experimental-transform-types or similar flag

Resolution

• Added .ts extensions to require statements where missing
• Investigated and resolved the missing callbackrequest model module
• Verified all 38 import paths consistent

Lessons

• server/db/models.ts is critical infrastructure - 35+ files depend on it
• Mixed ESM/CJS in the same file is a recurring source of issues
• Supervisor’s auto-restart fills logs fast; check supervisorctl status first
• Always git status first - repo was clean, bugs were in committed code
• The models.ts factory pattern (receives sequelize → returns models → stored in serviceContainer.dbModels) is the dependency injection core

vuer_oss Sequelize Import Error (March 2026)

Session: S220 Symptom: SyntaxError when importing CreationOptional from Sequelize

Context

• Sequelize’s TypeScript-only types (CreationOptional) used in runtime .ts files
• Without proper transpilation, Node.js can’t resolve TS-only exports from Sequelize
• Part of the broader FKITDEV-7855 TS/JS compatibility investigation

Waiting Time Display Bug — Race Condition (March 2026)

Ticket: FKITDEV-8521 / SLAMKB-17 Branch: fix/FKITDEV-8521 Symptom: Operators see phantom 3-hour waiting times or blank/zero times on the waiting list dashboard

Full Investigation

See FKITDEV-8521 for the complete fix with mermaid diagrams and code pointers.

3 Interacting Bugs in CustomerService.js

1. Null cache poisoning: userWaitingHistory.set(id, null) permanently cached — Map.has() returns true for null, DB never re-queried
2. Overly broad LIKE: %waiting-room% matched waiting-room-exit records, returning timestamps from previous sessions
3. Stale cache race: RPC path (join-waiting-room) wins race against queue-based pagevisit DB write; customerHistory:updated event existed but nobody listened

Root Cause Sequence

1. Customer enters waiting room → two independent RabbitMQ messages fire
2. Queue message (fire-and-forget) creates CustomerHistory pageVisit record
3. RPC call (request-response) adds customer to waiting line, triggers DB read
4. RPC is faster → reads DB before queue write completes → null or wrong record → cached permanently

Fix (commit 54001f0)

• Only cache valid records (skip null)
• Tighten LIKE to %"page":"waiting-room"%
• Listen for customerHistory:updated afterSave event to instantly refresh cache

Related

• vuer_oss - Backend server (most debugging happens here)
• infrastructure - Network/DNS issues
• agent-context - Quick reference
• FKITDEV-8521 - Full investigation with fix details