| name | flutterhelm-troubleshooting |
| description | Diagnose FlutterHelm failures and degraded states. Use when Codex needs to triage approval_required responses, SESSION_BUSY or WORKSPACE_BUSY, root or fallback problems, degraded delegate/provider health, runtime driver errors, native_build setup problems, or HTTP preview confusion. |
FlutterHelm Troubleshooting
Use this skill to triage FlutterHelm failures before changing config or code.
Triage order
- Read
workspace_show for activeRoot, transportMode, and resource pointers.
- Read
config://compatibility/current and config://adapters/current.
- If a session exists, read
session://<id>/health.
- Inspect the exact structured error code before proposing changes.
- Only move to beta setup when the failure is clearly outside the stable path.
Decision rules
- Treat
approval_required as a policy step, not a backend failure.
- Treat
SESSION_BUSY and WORKSPACE_BUSY as coordination issues first.
- Treat
RUNTIME_DRIVER_UNAVAILABLE, ADAPTER_PROVIDER_UNHEALTHY, and NATIVE_BUILD_PROVIDER_UNAVAILABLE as environment or provider issues first.
- Treat HTTP preview errors as transport limitations unless the user explicitly wants preview transport.
References
- Read
references/error-matrix.md for common error families and the next remediation step.
- Read
../../../../docs/12-troubleshooting.md when you need the repo's full troubleshooting guide.
