> For the complete documentation index, see [llms.txt](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/troubleshooting.md).

# Troubleshooting

## Build and dev

**`Failed to fetch dynamically imported module … client.tsx`** A hot-reload artifact after a broad edit. Hard-reload the page. If it persists, run `bun run build` — a passing production build confirms it is a dev-server artifact, not a code fault.

**Route not found after adding a file** `src/routeTree.gen.ts` regenerates on dev-server file watch. Never hand-edit it. Confirm the file is under `src/routes` with the expected name.

**Duplicate `/` route** Something claims `/` twice. Keep `src/routes/index.tsx` and delete the other claimant (`_app/index.tsx` or `_authenticated/index.tsx`).

**Tailwind build fails on `@import`** Lightning CSS resolves `@import` from the filesystem. Remote stylesheets and fonts load via `<link>` in `__root.tsx`. All `@import` rules must precede `@theme` and every other rule in `styles.css`.

## Server functions

**`process.env.X` is `undefined`** Read it inside `.handler()`. Env injection happens at call time, not module evaluation.

**`createServerFn is not a function`** Import from `@tanstack/react-start` — not `@tanstack/start`, not `@tanstack/react-router`.

**Build fails citing a `*.server` import a component never imports** A hook or shared util in the chain pulls it in, dragging the whole chain into the client bundle. Break the reachability of the server-only leaf, not just the route.

**`ReferenceError` at runtime although typecheck passed** A `*.functions.ts` file has runtime siblings at module scope. Server-function splitting deletes them. Move helpers, constants, and config into an imported module or inside the handler.

**`Error: Unauthorized` during build** A protected server function is being called from a public route loader; prerender has no session. Call it from the component via `useServerFn` inside `useQuery`.

## Data and quotes

**Status strip cells show degraded** Expected when a secret is missing or an upstream fails. Each cell is independent and only renders a value when its own request succeeded. Check `ROBINHOOD_RPC_URL`; without it the public RPC is used and rate-limits.

**Every quote fails** Check `routingConfigured()` — a missing `ZEROX_API_KEY` disables routing and the terminal states so. Sanitized errors deliberately omit upstream detail; look at server logs.

**`NOT_ELIGIBLE` on a firm quote** The claim is incomplete or the region is restricted. `RESTRICTED_REGIONS` overrides the default list; `OTHER` is restricted by design.

**Rate limited** Per-IP: 30/60s indicative, 12/60s firm quote. Debounce input rather than raising the limit.

**Price looks \~10× off** You are reading the underlying price where the multiplier-adjusted token reference belongs, or the reverse. See [Pricing](/bubblegum-reality-docs/architecture/pricing.md).

## Wallet

**Wrong-network banner will not clear** Success is only asserted after the wallet reports `4663`. If `wallet_switchEthereumChain` fails, the app falls back to `wallet_addEthereumChain`; some wallets require the user to approve both steps.

**WalletConnect option missing** `VITE_WALLETCONNECT_PROJECT_ID` is unset. It is publishable and belongs in client env.

**Approval succeeds, swap reverts** The spender must be `issues.allowance.spender` from the same quote response — never the Settler address. A stale quote's spender can differ.

## Landing media

**Video does not play** — expected under `prefers-reduced-motion`, and on a hidden tab; on error it collapses to the poster still. Video audio is permanently muted by design; the soundtrack is a separate gesture-gated `<audio>` element.

## Runtime environment

`[unenv] X is not implemented yet!`, `__dirname is not defined`, or a runtime `Cannot find module` all mean the package is Node-only and unusable in the edge Worker. See [Deployment](/bubblegum-reality-docs/operations/deployment.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.