Troubleshooting
Generation Fails or Produces Errors
| Possible Cause | Solution |
|---|---|
| Agent not found | The Desktop app bundles TF Code. Restart the app; if the issue persists, reinstall the Desktop app. |
| Insufficient UoI | Check your workspace UoI balance. Generation consumes UoI. |
| Background service not running | Restart the ToothFairyAI Desktop app. |
| Network issue | Media generation requires internet access to the ToothFairyAI backend. Check connectivity. |
Preview Shows a Blank Screen
| Possible Cause | Solution |
|---|---|
| Artifact not yet emitted | Wait for the agent to finish generating. Check the live todo progress. |
| Broken artifact framing | The agent may have malformed the <artifact> block. Ask it to re-emit. |
| JSX rendering error | If using JSX mode, check for syntax errors in the generated code. Use the in-app Lint action to diagnose. |
Images or Video Not Appearing
| Possible Cause | Solution |
|---|---|
| Media task still running | Check the media task indicator in the app for task status. Video generation is asynchronous. |
| Model not configured | Open Settings → Media Providers and select a default model. |
| Backend unavailable | The ToothFairyAI backend may be temporarily unavailable. Retry after a moment. |
Design System Not Applying
| Possible Cause | Solution |
|---|---|
| No system selected | Open the Design Systems tab and select a system before generating. |
| File not found | Ensure DESIGN.md exists at ./DESIGN.md or ./design-system/DESIGN.md. |
| Manifest invalid | Use the Desktop app's Validate action (Settings → Design Systems) to validate the manifest. Check for missing referenced files. |
Export Fails
| Format | Possible Cause | Solution |
|---|---|---|
| Browser print blocked | Ensure pop-ups are allowed for the Desktop app. | |
| PPTX | No slides.json | The skill must produce a slides.json structure. Use a deck skill if you need PPTX export. |
| ZIP | File access error | Check that the project directory is accessible and not locked by another process. |
MCP Server Not Connecting
| Possible Cause | Solution |
|---|---|
| Desktop app not running | Start the ToothFairyAI Desktop app. The MCP server requires the app to be running. |
| Not registered | Open Settings → MCP Server in the Desktop app and copy the install info, then register the MCP server with your coding agent. |
| Wrong working directory | Ensure the coding agent is configured to use the MCP server's stdio path. |
Connectors Not Working
| Possible Cause | Solution |
|---|---|
| Not authenticated | Open Settings → Connectors and authenticate with the service. |
| Tool disabled | Check the tool safety policy in Settings. Destructive tools are disabled by default. |
| Composio not configured | Open Settings → Connectors in the Desktop app and configure the Composio connector. |
Live Artifact Not Refreshing
| Possible Cause | Solution |
|---|---|
| No data source | The artifact must be backed by at least one connector. See Live Artifacts. |
| Connector auth expired | Re-authenticate the connector in Settings. |
| Refresh lock held | Another refresh may be in progress. Wait for it to complete or abort it. |
| Stale artifact | The data source may be unreachable. Check connector status and retry. |
Performance Issues
| Possible Cause | Solution |
|---|---|
| Large project | Projects with many files can slow the file workspace. Consider archiving old projects. |
| Long-running session | Use context compaction to reduce conversation length. Start a new conversation for unrelated work. |
| Too many media tasks | Media generation is resource-intensive. Avoid generating multiple videos simultaneously. |
Getting Help
- Support email:
support@toothfairyai.com - Logs: Use the Desktop app's Help → Diagnostics → View Logs to inspect background-service logs.
- Status: Use Help → Diagnostics to check whether the app's background service is running.
- Inspect: Use Help → Diagnostics → Run Report for a detailed diagnostic report.