chore(website): add troubleshooting doc

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

This change is part of the following stack:

• chore(website): add troubleshooting doc #4322 ◀
  • fix(rivetkit0: fix wf history diverged bug #4321
    • fix(frontend): fix inspector public path #4323

_{Change managed by git-spice.}

[railway-app]

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

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Feb 27, 2026 at 1:06 am
frontend-inspector	😴 Sleeping (View Logs)	Web	Feb 27, 2026 at 1:02 am
frontend-cloud	😴 Sleeping (View Logs)	Web	Feb 27, 2026 at 12:59 am
ladle	❌ Build Failed (View Logs)	Web	Feb 27, 2026 at 12:56 am
mcp-hub	✅ Success (View Logs)	Web	Feb 27, 2026 at 12:54 am

[claude]

PR Review: chore(website): add troubleshooting doc

This is a small docs PR that reserves a troubleshooting page slot and adds it to the sitemap.

Issues

Content is a placeholder

The file body is just TODO. Merging a publicly-visible documentation page with no real content creates a broken experience for users who land on it (e.g., from a search engine or internal link). Consider either:

• Adding at least a minimal set of real troubleshooting items before merging, or
• Keeping the page in a draft/hidden state until it has content (e.g., remove the sitemap entry and merge only once content is ready)

Sitemap placement vs. file path

The file lives at /docs/general/troubleshooting but is inserted into the sitemap under the Actors section (after /docs/actors/limits). This mirrors the existing pattern for /docs/general/cors, so it isn't wrong, but it may confuse contributors later who expect general-path pages to live in a separate section. If the intent is truly actor-focused troubleshooting, consider /docs/actors/troubleshooting to match its siblings.

Description scope

The frontmatter description says "Common issues and solutions when working with Rivet Actors" which is appropriately scoped if this page stays actor-focused. Just worth confirming that's the intended scope given the general/ path.

What's correct

• All three required frontmatter fields (title, description, skill) are present per CLAUDE.md conventions.
• The sitemap entry is correctly formatted and placed.
• The skill: true flag is set, consistent with other docs pages like limits.mdx.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/virtual-websocket

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

@rivetkit/cloudflare-workers

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4322

@rivetkit/traces

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

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4322

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: bd64ba0