Troubleshooting

This page is organized by symptom. Start with the problem you see. You do not need to check everything at once.

Cola Will Not Open or Is Stuck Starting

Fully quit Cola and reopen it. During startup, Cola prepares both the desktop interface and the local service. Relaunching often clears temporary startup stalls.

If it is still stuck, include today's logs when reporting the issue:

tail -n 100 ~/.cola/logs/cola-$(date +%F).log

Look for these clues:

• address already in use: the local service port is occupied.
• permission denied: file or system permission problem.
• model not found or provider: model configuration or account authorization problem.
• Repeated restart or crash: the local service crashes after startup.

If you are not comfortable with Terminal, send a screenshot of the error and the time it happened to support.

If a non-closable Initializing, please wait… window appears at startup, that is Cola refreshing a local snapshot before touching existing data. It is a normal wait and hands over to the main window when it finishes — don't force-quit. See Backup, Migration, and Uninstall.

Blank Window or the Interface Disappears

If the interface process crashes, Cola reloads the page on its own — usually you just see the window flicker and come back, with nothing for you to do. Work already running continues in the local service and is unaffected.

Automatic recovery is attempted once. If that attempt also fails, Cola shows a dialog with a single Quit button:

• Cola could not recover the page. Please quit and open the app again. — the interface crashed after the app was already up.
• Cola could not start. Please quit and open the app again. — the interface never loaded in the first place.

In both cases click Quit, then open Cola again. If it keeps happening, report it using the steps below with today's logs and the time it occurred.

Cannot Connect to Local Server

If the interface says the local server is not connected, quit and reopen Cola first.

If it still cannot connect:

• Confirm that multiple Cola copies are not open at the same time.
• Restart the Mac and open Cola again.
• Check whether security software is blocking local app communication.
• When reporting the issue, include logs from the relevant time under ~/.cola/logs/.

Cannot Sign In or Keeps Signing Out

First confirm that the network can reach Cola cloud services, then sign in again.

If the problem repeats, check:

• Whether system time is correct. A large time difference can invalidate login credentials.
• Whether a proxy, company network, or firewall blocks OAuth, email verification codes, or the Cola API.
• Whether multiple Cola windows or versions are open.

Do not manually edit Cola's local configuration files. If you need to clear login state, prefer in-app sign-out or account settings.

Model Unavailable or Task Fails Immediately

Model issues often appear as tasks failing immediately, or logs containing words such as model not found, provider, apiKey, baseUrl, 401, or 403.

First, choose an available model tier again in Settings. If you use account-provided hosted models, signing in again usually refreshes model configuration and authorization.

If you use a custom model or your own API key, check that the model name, service URL, and key are still valid. After changing them, fully quit and reopen Cola.

Notification Sound Preview Is Silent

In Settings > Notifications > Notification Sound, every option that has a sound has a Preview notification button beside it. Pressing it pops a notification and plays that sound at the same time.

If you see Unable to preview the sound. Check your system sound settings., the audio itself did not play:

• Check the system output device and volume first — a muted system has nothing to play.
• With System Default selected, Cola plays the system's own notification sound. On Windows, the preview fails when the current sound scheme has no sound assigned to the notification event; assign one in the system sound settings.
• Preview is supported on macOS and Windows only.

That message is about sound only. If the notification itself never appears, Cola's notifications are usually turned off at the system level — enable them in your system notification settings.

Previewing is separate from a real notification. On macOS, a real notification's sound is played by the system, so Do Not Disturb, a Focus mode, or a muted notification sound for Cola silences it even though the preview still plays normally.

Voice Button Does Nothing

First check macOS microphone permission:

System Settings > Privacy & Security > Microphone

Confirm that Cola is allowed to access the microphone, then restart the app.

If it still does nothing:

• Confirm in Settings that Voice Shortcut is not disabled.
• Try another microphone device, or switch back to the system default.
• Confirm that no other app has exclusive control of the microphone.
• Check logs for speech-recognition initialization failures.

The default Voice Shortcut is Option on macOS. If you changed it, use the value shown in Settings.

Voice Records but Recognition Is Poor

Move to a quieter environment, get closer to the microphone, and try a short sentence.

Then check:

• Whether the system input device is wrong.
• Whether Bluetooth headphones switched into low-quality call mode.
• Whether the input language differs from the language you are speaking.
• Whether wind, music, meeting audio, or other voices interfere.

Cola's speech recognition is local. A slow network usually does not make recognition worse, but it can affect task submission and model replies after recognition.

Task Keeps Running or No Reply Appears

First check whether the interface is still streaming output, calling tools, or processing subtasks. Longer tasks can take a few minutes.

If it is clearly stuck:

• Send "Where are we now?".
• Ask Cola to stop the current task and summarize what has already been done.
• Quit and reopen Cola so the local service reconnects.

If every run gets stuck at the same step, check logs for tool names, commands, file paths, or network errors. Send that log section together with your task description to make diagnosis easier.

File Was Not Generated or Cannot Be Found

First check the Outputs or Tasks area in the interface. User-visible files generated by Cola usually go to the output directory. You can also check:

ls ~/cola/outputs

If the task did not explicitly ask for a file, Cola may have replied only in chat. Next time, say:

Write the result as a Markdown file and tell me the file path.

Configuration Seems Broken

Cola's main local data is in ~/.cola/. Settings, sessions, models, memory, and logs are runtime state and should not be edited manually.

If you think configuration is corrupted, quit Cola and contact support first. Do not delete the whole ~/.cola/ directory unless you have confirmed that you do not need historical sessions, memory, tasks, or output files.

Where to Report

You don't have to leave Cola: type /feedback in the composer to open the "Share your feedback" window, or fill in the inline form under Settings > About > Submit logs. Ideas, suggestions, complaints, and bug reports are all welcome, and every one goes straight to the Cola team.

• You can attach screenshots (up to 4).
• You can attach logs, choosing a window of 1 hour, 1 day, or 3 days — Cola packages the matching logs automatically.
• You need to be signed in.

What to Include When Reporting

Before reporting, prepare:

• The Cola version you are using.
• The time the issue happened.
• The task content you entered.
• A screenshot or the exact interface message.
• Logs from the relevant time under ~/.cola/logs/.

Logs may include file paths, task content, or account-related errors. Review them first and remove private content you do not want to share.