Troubleshooting

This page collects common operational issues that follow from the source-verified configuration and workflow model.

Server Does Not Start

For source builds, confirm Go 1.26.6+ is installed.
If auth is enabled, confirm AUTH_USERNAME, AUTH_PASSWORD, and AUTH_SESSION_SECRET are all set.
Check logs/openvibely.log when using ./start.sh.
Ensure the selected PORT is available.

Open a new terminal after installation so the shell reloads its command lookup and PATH.
On macOS or Linux, run command -v openvibely or command -v openvibely-desktop.
On Windows, reopen PowerShell and run Get-Command openvibely or use the Start Menu shortcut.
If an old command points to a deleted installation, remove that stale command or symlink and rerun the hosted installer.

Confirm the running app is a released desktop or binary build. Source builds do not self-update.
Open Alerts and inspect the current version, release channel, and update state.
Confirm a newer release has been promoted to the app's configured channel.
Restart the app if it has not completed its periodic release check.

Read the exact failure shown in Alerts; the updater restores the previous version when the replacement does not start or report healthy.
Rerun the hosted installer with the same desktop or binary variant to repair the application files. App data is stored separately and remains in place.
Do not normally delete update-state.json, update-coordinator.json, or update-drain.json by hand. The app and installer coordinate unfinished recovery.
See Updates for the complete update and reinstall flow.

Set APP_BASE_URL to your public origin, for example https://app.example.com.
Use OAUTH_REDIRECT_MODE=auto or hosted.
Ensure provider callback URLs match the app callback routes.

Confirm the project has a local repo_path.
Confirm memory is enabled for the project.
Check Memory Curator lifecycle activity or System: Memory Consolidation run status for error.
Remember memory writes to .openvibely/memories inside the selected repo.

Check global worker capacity.
Check project max_workers.
Check model max_workers and worker_timeout.
Confirm the selected model credentials are valid.
For swarms, remember the parent's Max workers limits planned slices but does not override execution capacity.

Open the task error and project Alert; OpenVibely fails closed instead of modifying the main checkout.
Confirm the repository exists, its merge target is valid, and Git can create a worktree.
Create an initial commit before running repository-changing tasks in a new empty repository.

Add the sender to the system-level Authorized Users or Senders list; Slack, Telegram, Discord, and Email are deny-by-default.
For Discord server channels and threads, mention the bot and verify Message Content Intent and channel permissions.
For Email, confirm the message is unread, not self-sent or automated, and IMAP polling is connected.
Verify the channel's active project when work appears in an unexpected workspace.

Confirm the platform channel is configured and the selected project has a matching saved or Home target.
Test the target from Channels -> Outbound Message Targets.
Enable Allow explicit unsaved targets only when the prompt intentionally uses an unsaved destination.
Confirm Chat is in Orchestrate mode and the selected provider/agent supports send_message.

Assign the issue to the PAT owner or a configured GitHub Authorized User.
Remove stale prompt requirements for an existing PR or mandatory approved label.
Keep recurring inbox/finder tasks schedule-driven; put persisted goals on implementation tasks instead.
Confirm the implementation task has a worktree branch before publishing its pull request.