Troubleshooting
First note the current organization, project, task, and exact error. Then use the relevant checks below.
Sign-in and organization selection
| Symptom | Check |
|---|---|
| Sign-in dialog was closed or the app is not ready | Complete authentication in Aru’s browser dialog. Closing it cancels sign-in, so start again from the welcome screen. |
| Network is not allowed | Confirm the organization’s allowed network or required company access. |
| Membership pending or inactive | Ask an administrator to review membership. |
| Keychain access error | Review the macOS prompt, restart Aru, and allow access to sign-in information. |
| Workspace could not start | Check network and app version, retry, and record the error and version if it continues. |
Finish active work before switching organizations.
No model or cannot start a request
If Aru shows No model, check the organization, plan or credits, and model policy with an administrator. Confirm that a model is selected in the composer.
A task appears stuck
- Check for Permission needed or Input needed.
- Respond to the open card or question.
- Check whether a tool is still running or retrying.
- Select Stop if needed.
- Review completed changes and remaining processes before continuing.
For an external create or update request, check the service before retrying to avoid duplicates.
Cannot use MCP
| Status | Check |
|---|---|
| Service missing | Check the organization catalog and access. |
| Authentication required | Authenticate or reauthenticate. |
| Connection failed | Check server URL or command, required settings, network, and Test. |
| Installed but tools missing | Check enabled state and Available projects. |
| Pending application | Wait for the current run to finish, then check again. |
| Settings failed to apply | Retry local application. |
| Installation unknown | Refresh before retrying. |
| Blocked by policy | Ask an administrator about policy and access. |
For plugin MCP, also check the plugin and authentication. See MCP connections.
Plugin and skill errors
For plugin installation failures, review the result, app version, and network. If a selected plugin is unavailable, enable it or remove it from the composer. For missing skills, check location, enabled state, and owning plugin. Imports must contain a valid SKILL.md in a folder or ZIP.
Cannot open or save a file
Confirm the project or worktree, file path, folder location, and OS access. Use Open in default app for unsupported previews. For save failures, check write permission and editor save mode. After a partial Git revert, inspect remaining files before retrying.
Browser problems
- Page unavailable: Check sign-in and site access.
- Interaction failed: Complete the blocked step yourself, then continue.
- Upload failed: Check the file path and allowed type and size.
- Download missing: Check completion and save location.
- GPU acceleration unavailable: Check graphics settings and restart Aru.
Clearing browser data under Settings → About removes cookies, storage, and permissions and may sign you out.
Image and Office results
For image editing, attach a PNG or JPEG and confirm feature availability. For Office creation, check required plugins. Review final files in the app you will use when preview differs.
Update failed
Check the network and OS installation permission, then follow retry prompts. See Updates.
When contacting support
Provide the OS and Aru version, feature and steps, exact error and time, expected and actual result, and actions already tried. Remove account data, tokens, and work material from screenshots and logs.