Troubleshooting
Start with the app version, operating system, and exact failed step. Do not delete your data directory or overwrite your only backup to diagnose an issue.
Startup fails after upgrading
Section titled “Startup fails after upgrading”Version 0.6.2 fixes startup issues involving old database paths and historical browser data. Preview 0.6.3-beta.1 further fixes unrecognized Skill directories and older recovery files blocking startup or restore; it is not the stable release.
- Save the startup error details. Review copied logs for sensitive content before sharing.
- Preserve the workspace and backups, then use offered recovery choices to resolve conflicts.
- Back up before trying the preview and read its release notes.
CLI or external edits do not appear
Section titled “CLI or external edits do not appear”Refresh the workspace. Version 0.6.2 refreshes lists, details, tags, and counts while protecting unsaved drafts. Save or resolve edits before accepting external changes; restarting is not a required routine step.
A distributed Skill or Plugin is missing
Section titled “A distributed Skill or Plugin is missing”- Confirm the Agent root matches the tool you are actually using.
- Apply changes adds or removes targets; Redistribute updates existing copies.
- Inspect failed targets and verify that package scripts and references are complete.
- Linked installations depend on the source directory remaining accessible.
- Resolve external target edits before approving an overwrite.
Model calls or image generation fail
Section titled “Model calls or image generation fail”Check endpoint, API protocol, credentials, and model capabilities. Vision understanding and image generation are different capabilities; reference-image editing needs an appropriate editing API too. Follow the service’s actual error rather than assuming support from a model name.
Self-hosted backup is rejected
Section titled “Self-hosted backup is rejected”Desktop and server must run the exact same version. Test backup support and account permissions. Automatic jobs upload only. The experimental Cloudflare version’s older sync API is not the desktop backup endpoint. See Self-hosted Web.
Sign-in or identity linking fails
Section titled “Sign-in or identity linking fails”Start authorization again from the sign-in page rather than revisiting an old callback URL. If a provider is unavailable, use another identity already linked to the same UID; an unlinked identity may create a separate account. An identity belonging to another UID cannot be linked or merged.
Report a problem
Section titled “Report a problem”Use GitHub Issues with the version, OS, minimal reproduction steps, error text, and redacted screenshots. Do not attach secrets, cookies, complete production backups, or private repository contents.