Reliability: what can stall or take vid2context down#
An audit of hang and crash risks per surface, with the file and line where each one lives (line numbers as of 2026-11-15), and what was done about it. "Fixed" means the change and a test are in the tree; "open" means it is known and left for the owner of that code.
Every limit below has an env var with a safe default. They are listed in .env.example and docs/providers.md.
The timeout middleware answered 504 but left the work running; only ctx.signal stops it.
src/middleware.ts:127 races next(); src/services.ts:142 folds AbortSignal.timeout into ctx.signal
Fixed earlier (deadline in ctx.signal), 499 for client aborts in src/errors.ts
No cap on concurrent expensive requests (context, transcript, pack, bundle, ask, briefs, MCP tool calls): a burst runs every pipeline at once and exhausts memory, sockets and yt-dlp slots.
routes mount with no limiter, src/app.ts
Fixed: src/concurrency.ts (VID2CONTEXT_MAX_CONCURRENT, VID2CONTEXT_MAX_WAITING, VID2CONTEXT_QUEUE_WAIT_MS), 503 busy with Retry-After
/api/v1/health is liveness only: a container whose storage, disk or binaries are broken still looks healthy.
src/app.ts:267
Fixed: GET /healthz and /healthz?deep=1 (also /api/v1/healthz) check storage, rungs, disk space, yt-dlp, ffmpeg and the keyless network; 503 when a required check fails (VID2CONTEXT_HEALTH_REQUIRE), cached and single-flight (src/health.ts, src/health-node.ts)
Shutdown waited for server.close(), which never resolves while an SSE client (job events, MCP GET stream) stays connected, so such deploys ended in the forced exit(1).
src/node.ts:68 (before)
Fixed: src/lifecycle.tsgracefulClose gives requests half of VID2CONTEXT_SHUTDOWN_TIMEOUT_MS, closes MCP sessions, jobs and downloads, then cuts what is still open
An unhandled promise rejection anywhere in the process exits Node 22 and ends every in-flight request.
src/node.ts had no handler
Fixed: logged with the stack, the process keeps serving (VID2CONTEXT_EXIT_ON_UNHANDLED=1 restores the exit)
Slow clients (slowloris) could hold sockets; Node's defaults were not configurable and are only checked every 30 s.
src/node.ts:50 (before)
Fixed: VID2CONTEXT_HEADERS_TIMEOUT_MS, VID2CONTEXT_BODY_TIMEOUT_MS, VID2CONTEXT_KEEPALIVE_TIMEOUT_MS, passed at server creation with a matching check interval
Request bodies: JSON routes are capped by bodyLimit (VID2CONTEXT_MAX_BODY_KB), uploads by VID2CONTEXT_MAX_UPLOAD_MB, /imports caps its own at 5 MB. /mcp and /oauth/* are outside /api/* and had no cap.
Large transcripts: responses are built in memory (JSON.stringify, ETag hash). Bounded by VID2CONTEXT_MAX_SEGMENTS (200000) in core, which keeps one response to tens of MB.
src/http-util.tsjsonWithEtag
Acceptable; no change
Single-flight runs use their own timeout signal, so a run nobody waits for any more still runs to its deadline (it fills the cache).
src/services.ts:206
Acceptable by design
Remote MCP (packages/mcp-http) and stdio MCP (packages/mcp)#
Risk
Evidence
Status
POST /mcp and the OAuth form posts read the whole body with no size limit.
src/transport.ts:106, src/oauth.ts
Fixed: VID2CONTEXT_MCP_MAX_BODY_KB (default 1024), 413 before the SDK parses
Session mode builds the server with no signal, so a tool call has no deadline of its own; only the client's notifications/cancelled or the session closing stops it.
Hardened in this round by another session (stall and per-attempt timeouts, a cap on queued jobs, a Retry-After clamp, the slot held on abort); see packages/jobs and jobs.md. Findings from this audit passed to that owner:
Risk
Evidence
Status
A handler that never settles and ignores its signal holds a concurrency slot forever.
src/execute.ts:153raceAbort only rejects on abort
Fixed: the stall watchdog aborts it, the slot is freed after a 5 s grace (src/watchdog.ts)
On start, every running record is requeued, including jobs another live process sharing the store is still running (no heartbeat on the record).
src/queue.ts:126
Fixed: running attempts heartbeat every 30 s; a fresh running record is watched and taken over only when stale or handed back
enqueue grows pending without bound.
src/queue.ts:144
Fixed: VID2CONTEXT_MAX_QUEUED_JOBS (1000), then rate-limited
close() aborts running jobs at once instead of draining them.
src/queue.ts:193
Jobs owner; the server's shutdown gives it half the grace period before cutting connections
Cloud Tasks token, enqueue and JWKS fetches use ctx.fetch with no timeout.
src/cloud-tasks.ts:85, :104, :200
Fixed: 15 s deadline, then timeout
The SSE heartbeat timer writes into the stream without a try; a write after the consumer is gone throws from a timer.
A request aborted while waiting for a YTDLP_CONCURRENCY slot stayed in the wait list; when woken it took the slot and spawned yt-dlp anyway, because an abort listener added after the abort never fires. The process then ran to its full timeout. The wait list was unbounded.
src/process.ts:54, :57, :136 (before)
Fixed: waiters leave the queue on abort and slots pass to the next live waiter; spawn checks the signal; YTDLP_MAX_WAITING (64) refuses more as busy. Timeout hints name the caller's env var (timeoutEnvVar)
YouTube changes break extraction until the weekly update check runs.
src/binary.ts:23 (weekly), src/errors.ts:90
Fixed: an extractor error that yt-dlp marks as needing an update ("Confirm you are on the latest version using yt-dlp -U", recorded from yt-dlp 2023.03.04 against YouTube and Vimeo) triggers an immediate checksum-verified update of the managed binary, at most once per YTDLP_SELF_UPDATE_MIN_SEC (default 6 h) across processes, and one retry. The hint says whether it updated, was already latest, was too soon, or is a user binary
An old binary is invisible until it breaks.
packages/cli/src/doctor/run.ts
Fixed: doctor and /healthz?deep=1 warn when yt-dlp is older than YTDLP_STALE_DAYS (default 60)
Every child has a timeout, kills its process group on abort and caps stdout and stderr.
Owned by another session in this round. The per-rung timeout (VID2CONTEXT_RUNG_TIMEOUT_MS, default 180 s, local rungs exempt) and the stop-on-abort check before each rung are in chain.ts. Remaining risk: a timed-out rung's call keeps running until the request signal ends, because runChain cannot hand the call a signal of its own without a change to the call(rung) signature in pipeline.ts.