Troubleshooting¶

Symptom	Check and fix
`pyreact-forge` command not found	Activate the environment or use `python -m pyreact_forge.cli --help`. Install with the same Python executable.
`No matching distribution found`	Before first publication use the supplied wheel/source. After publication select `==0.1.0a1` or `--pre`; confirm Python 3.11+.
`RuntimeRequiredError`	UI code was executed in native CPython. Use `dev`, `render`, or a browser integration.
`Starting Python…` never finishes	Inspect browser Network/Console; check CDN access, correct runtime files and MIME types. Try a vendored runtime.
Offline runtime not found	Run `vendor`, or set `PYREACT_FORGE_PYODIDE` to a directory with the complete runtime.
Empty page after opening `index.html`	Serve over HTTP/HTTPS instead of `file://`.
Invalid child `dict`	Render selected fields, not the whole Python dictionary.
Hook-order or invalid-hook-call error	Call hooks only at the component/custom-hook top level; check for a second React instance in JS extensions.
Input does not update	Use controlled `value` plus `on_change`; convert the JS value with `str(...)` where appropriate.
State update has no visible effect	Create a new object; mutating a state dict/list in place does not schedule React work.
Every row action targets the final item	Capture the loop ID in a default argument, as shown in the task tutorial.
Effect return-value error	Return `None` or a cleanup function, not an expression returning a number or an async coroutine.
Suspense keeps restarting	Create the resource outside render and use a stable, hashable key.
Request blocked by CORS	The browser's network rules apply to Python too; configure the API response rather than embedding server credentials.
`/about` works by clicking but fails on reload	Configure your static host's `index.html` fallback.
Broken assets on GitHub project Pages	The app exporter assumes origin-root hosting; only the docs site currently supports a project subpath.
SSR fails on `document`	Move browser-only work into an effect/event.
SSR reports custom modules/packages unsupported	The CLI intentionally rejects those combinations in this alpha.
Hydration mismatch	Make initial route, state and markup deterministic and identical on server/client.

Read installation, effects, async data and deployment for complete examples. A reproducible small project and its full traceback are more useful in a report than a screenshot alone.