fix(rivetkit): add config parameters to spawned serverless engine for local dev

[NathanFlurry]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-3994 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-inspector	😴 Sleeping (View Logs)	Web	Jan 22, 2026 at 4:37 am
frontend-cloud	😴 Sleeping (View Logs)	Web	Jan 22, 2026 at 4:36 am
website	😴 Sleeping (View Logs)	Web	Jan 22, 2026 at 1:52 am

[NathanFlurry]

• fix(rivetkit/next-js): fix request handler #4001
• fix(rivetkit): handle undefined options with scheduling #4000
• chore(engine): add force shutdown timeout #3999
• fix(rivetkit): fix fetch handler in nextjs serverless #3998
• fix(rivetkit): add back dev hot reloading in next #3997
• fix(rivetkit): fix routing of /websocket #3995
• fix(rivetkit): add config parameters to spawned serverless engine for local dev #3994 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Pull Request Review: fix(rivetkit): add config parameters to spawned serverless engine for local dev

This PR improves the local development experience by adding development-optimized configuration parameters and better error diagnostics for the spawned serverless engine.

✅ Positive Changes

1. Development-Optimized Timeouts (lines 99-121)
The addition of environment variables for Pegboard configuration significantly improves the local development experience:

• Reduced retry/backoff timeouts prevent actors from becoming unresponsive during frequent dev server restarts
• Clear comments explain the rationale and impact of each configuration
• Appropriate values for development iteration (100ms retries, 1s shutdown durations)

2. Enhanced Error Detection (lines 132-179)
The stderr capture and parsing provides much better developer experience:

• Specific error detection for RocksDB lock conflicts
• Helpful guidance for version downgrade scenarios with actionable fix command
• Log file paths included in all error messages for debugging

3. Structured Logging
Good adherence to the project's structured logging conventions using tracing-style field notation.

---

🔍 Potential Issues

1. Memory Leak Risk (lines 133-137)

const stderrChunks: Buffer[] = [];
if (child.stderr) {
    child.stderr.on("data", (chunk: Buffer) => {
        stderrChunks.push(chunk);
    });

Issue: If the engine process runs for an extended period and produces significant stderr output, the stderrChunks array will grow unbounded in memory. This is especially problematic if the process doesn't exit quickly or if there's verbose logging.

Recommendation: Consider one of these approaches:

• Set a maximum buffer size and only keep recent chunks
• Only capture stderr for the first N seconds after startup
• Use a ring buffer or limit total bytes collected
• Stream stderr to file and only read it back when the process exits

Example fix:

const MAX_STDERR_BYTES = 1024 * 100; // 100KB limit
let stderrSize = 0;
const stderrChunks: Buffer[] = [];

if (child.stderr) {
    child.stderr.on("data", (chunk: Buffer) => {
        if (stderrSize < MAX_STDERR_BYTES) {
            stderrChunks.push(chunk);
            stderrSize += chunk.length;
        }
    });
    child.stderr.pipe(stderrStream);
}

2. Error Detection Timing (line 147)

child.once("exit", (code, signal) => {
    const stderrOutput = Buffer.concat(stderrChunks).toString("utf-8");

Issue: The error detection only happens on process exit. If the engine crashes immediately on startup due to these specific errors, this works well. However, if the process hangs or exits later, the developer won't see these helpful messages until much later.

Recommendation: Consider checking for these error patterns earlier during the waitForEngineHealth() phase, so developers get immediate feedback if there's a known issue.

3. Configuration Values Hard-coded (lines 109-120)

Issue: The timeout and threshold values are hard-coded as strings. While appropriate for development, there's no validation or documentation of what the "production" defaults are.

Recommendation:

• Consider adding comments showing the production defaults for comparison
• Consider making these configurable via an optional parameter if users need different values for their dev environments

Example:

// Production default: 30000ms, reduced to 100ms for dev
RIVET__PEGBOARD__RETRY_RESET_DURATION: "100",

---

🤔 Questions & Suggestions

1. Unit Values Inconsistency

• Lines 109-117: Values appear to be in milliseconds ("100", "5000", "7000")
• Lines 119-120: Comment says "in seconds" but values are "1"

Could you clarify if these are all milliseconds or if there's a unit mismatch? The comment on line 118 suggests seconds, but "1" seems extremely short for a shutdown duration.

2. Error Message Consistency

• Line 152: "another instance of rivet engine is unexpectedly running, this is an internal error"
• Line 162: "rivet engine version downgrade detected"

The first message uses lowercase and says "internal error", while this is actually a user-recoverable condition with helpful guidance. Consider rephrasing to be more consistent with the helpful tone of the second message.

3. Test Coverage
There don't appear to be tests for the new error detection logic. Consider adding tests for:

• Stderr parsing for RocksDB lock errors
• Stderr parsing for version downgrade errors
• Buffer handling edge cases

---

📊 Summary

Code Quality: ✅ Good - follows project conventions, well-commented
Potential Bugs: ⚠️ Memory leak risk with unbounded buffer growth
Performance: ✅ Good - development optimizations are appropriate
Security: ✅ No concerns
Test Coverage: ⚠️ Missing tests for error detection logic

Recommended Actions

1. Critical: Add bounds checking to stderr buffer collection to prevent memory leaks
2. Important: Clarify unit consistency in configuration comments
3. Nice-to-have: Add unit tests for error detection
4. Nice-to-have: Consider early error detection during health check phase

Overall, this is a valuable improvement to the developer experience. The main concern is the unbounded buffer growth which should be addressed before merging.

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3994

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3994

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3994

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3994

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3994

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3994

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3994

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3994

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3994

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3994

commit: 47530e5

[graphite-app]

Merge activity

• Jan 22, 6:58 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Jan 22, 6:59 AM UTC: CI is running for this pull request on a draft pull request (#4007) due to your merge queue CI optimization settings.
• Jan 22, 7:00 AM UTC: Merged by the Graphite merge queue via draft PR: #4007.