Troubleshooting

No bridge found

Run the command from the app folder:

npx @genie-react/cli doctor \
  | jq '{ok, bridgeCandidates, remediation}'

Follow the returned remediation entries. Start the dev server or standalone hub, then inspect the status connection phases separately:

npx @genie-react/cli status --verbose

Use status --verbose for connection diagnostics; doctor accepts --live for stack probes.

More than one bridge matches

Move into the correct app folder or pass --url. Genie stops on ambiguity instead of guessing.

No ready session

Open the app in a browser, then wait:

npx @genie-react/cli call devtools_wait \
  '{"condition":"ready","timeoutMs":10000}'

More than one tab matches

Name the tab with ?_genie=my-agent, then set GENIE_SESSION=my-agent.

Query or Router tools are missing

Render <Genie /> near the matching provider. Pass queryClient or router directly if automatic discovery cannot see it.

React tools are missing

The hook must load before React. Check the Vite plugin or make the manual client script the first script in the document head.

JSON parsing fails

Check CLI release compatibility for older versions that emit text. On the current CLI, parse batch and call --fields as JSONL, and read verbose diagnostics from stderr separately.

A result is incomplete

Read its limit, truncation, and coverage fields. Use a smaller flow, a component filter, rootId, a larger allowed limit, or a focused package filter.

A Query wait is ambiguous

Use the exact queryHash or structured queryKey returned by query_list.

The app is busy

Wait for the returned retry delay. A blocked main thread cannot answer a runtime tool safely.