nexmoe--vidbee/apps/desktop/docs/sentry-fixes.md

Sentry / GlitchTip Fix Log

This log records remediation work on Sentry / GlitchTip issues for the vidbee project (org=nex, host=error.102417.xyz, release=vidbee-desktop@<version>).

Each entry captures: root cause, fix summary, files touched, validation output, current GlitchTip status, and any follow-ups.

2026-05-01 — VidBee Desktop quad-issue sweep (NEX-60)

Validation common to all four entries below:

• pnpm run typecheck — pass
• pnpm run check (ultracite check && check:i18n && typecheck) — pass
• pnpm run build — pass

The local repo has no sentry-cli credentials configured, and the project description allows skipping the resolved step in that case. None of the four GlitchTip issues were marked resolved from this branch; the next release of vidbee-desktop@1.3.11 (or the version that includes these commits) is the right point for the maintainer to flip them to resolved.

VIDBEE-6SV — RangeError: Invalid string length in main-process Socket

• Sentry: https://error.102417.xyz/vidbee/issues/7849
• Level: fatal · events: 4319 · last seen: 2026-04-27 (release 1.3.10, Windows)
• Root cause: yt-dlp / ffmpeg child-process stdout/stderr was being accumulated into a single JavaScript string for the lifetime of the process. On long downloads, large playlists, or verbose runs the string exceeded V8's ~512 MB limit and threw RangeError: Invalid string length. Five distinct sites had this pattern; the dominant one was executeDownload's ytDlpLog (live for the entire download), which matches the 4 319 fatal-event volume.
• Fix: introduced createBoundedTextBuffer (8 MB cap, single-shot truncation notice) in src/main/lib/bounded-output-buffer.ts and rewired all yt-dlp / ffmpeg readers to use it.
• Files:
  • src/main/lib/bounded-output-buffer.ts (new)
  • src/main/lib/download-engine.ts (getVideoInfo, getVideoInfoWithCommand, getPlaylistInfo, executeDownload)
  • src/main/lib/watermark-utils.ts (runFfmpeg)
• GlitchTip status: unresolved (no auth token locally)
• Follow-up: confirm by tail-watching error.102417.xyz/vidbee/issues/7849 for new events on the next release. Resolve once a stable run shows zero new fatal RangeError: Invalid string length events for ≥ 7 days.

VIDBEE-68 — yt-dlp Postprocessing / generic createError noise

• Sentry: https://error.102417.xyz/vidbee/issues/305
• Level: error · events: 1 325 (group 68 alone) · last seen: 2026-04-30
• Root cause: every yt-dlp child-process error funnelled through YTDlpWrap.createError, then download-engine re-emitted it as a download-error and index.ts captured it to GlitchTip with fingerprint = ['download-error', error.name, error.message]. The raw stderr blob in error.message made fingerprints unstable, scattered groupings (E / DE / 1G / 6I / 2 / 6FN / 2A …), and buried the small number of genuine VidBee defects under upstream / user-side noise.
• Fix: added classifyDownloadError (in src/shared/telemetry/yt-dlp-error-classifier.ts) that maps an error to one of postprocessing | http-error | unsupported-url | access-denied | unavailable | rate-limit | network | auth-required | drm-protected | no-format | cookies-required | environment | cancelled | unknown. The download-error listener in src/main/index.ts now skips captureMainException only when the matched rule is marked operational, and tags captured events with download_error_category so future grouping is stable.
• Follow-up filter audit (NEX-114): generic HTTP failures, generic postprocessing failures, extractor/parser failures, broad TLS timeout strings, bare Windows error codes, and bare AggregateError subscription failures were made reportable again. The operational list now keeps only narrower user-state, source-availability, and environment cases quiet, while still preserving category tags for the reportable cases.
• Files:
  • src/shared/telemetry/yt-dlp-error-classifier.ts (new)
  • src/main/index.ts (download-error listener)
• GlitchTip status: unresolved
• Follow-up: monitor for ≥ 1 week on a release that ships this change. If the unknown bucket is small and stable we can resolve VIDBEE-68 and the E/DE/1G/6I/2/6FN/2A siblings. If a new operational pattern appears, extend CATEGORY_RULES rather than re-listing it in issue-filter.ts (the classifier is the source of truth now).

VIDBEE-16 — DrizzleError: ALTER TABLE add yt_dlp_command

• Sentry: https://error.102417.xyz/vidbee/issues/67
• Level: error · events: 156 · last seen: 2026-04-19 (release 1.3.7, Windows)
• Root cause: legacy 1.3.x desktops applied the yt_dlp_command column via a raw ALTER TABLE on an older release; their __drizzle_migrations table no longer matched the journal hash, so re-running the migration threw SqliteError: duplicate column name: yt_dlp_command on startup. reconcileLegacyMigrationState was already added in 1.3.8 but doesn't cover every drift case.
• Fix: in src/main/lib/database/migrate.ts added matchDuplicateColumnError and findLegacyMigrationForColumn. When migrate() throws a duplicate-column error we look up which legacy migration adds that column, backfill its hash into __drizzle_migrations, and retry once. SQLite has no ADD COLUMN IF NOT EXISTS, so this self-heal pattern is preferred over rewriting the journal.
• Files:
  • src/main/lib/database/migrate.ts
• GlitchTip status: unresolved
• Follow-up: the original error was already trending down post-1.3.8. With the duplicate-column retry we expect it to drop to zero on the next release. Mark resolved when no events are seen for ≥ 14 days.

VIDBEE-H8 — Renderer process became unresponsive

• Sentry: https://error.102417.xyz/vidbee/issues/712
• Level: warning · events: 108 · last seen: 2026-04-29 (release 1.3.10, Windows)
• Root cause: Electron's unresponsive event has no JS stack, so previous reports were unactionable. The task description explicitly accepts diagnostic-only work for this one.
• Fix:
  • Main process (src/main/index.ts): only capture unresponsive after a sustained 5 s freeze (Electron emits transient hangs too). Record the measured unresponsive_ms on both the captured warning and on the responsive recovery message, so a 6 s blip and a 60 s lockup can be told apart in GlitchTip.
  • Renderer (src/renderer/src/main.tsx): install a PerformanceObserver({ entryTypes: ['longtask'] }) that adds a performance breadcrumb (with duration / startTime) for every synchronous task ≥ 200 ms. Breadcrumbs ride along on the next captured event, which gives us a localized hint on what was blocking the main thread when the freeze started.
• Files:
  • src/main/index.ts (setupRendererErrorHandling)
  • src/renderer/src/main.tsx (setupLongTaskObserver)
• GlitchTip status: unresolved (diagnostic-only) — by design. We intentionally did not attempt a code fix because we don't yet know which workload causes the freeze.
• Follow-up: once the diagnostic data lands in GlitchTip on the next release, group VIDBEE-H8 events by the new unresponsive_ms and long-task breadcrumb names to identify the worst offenders. Open follow-up tickets for the specific code paths instead of trying to resolve VIDBEE-H8 directly.