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.

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/.

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.

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.

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.

Troubleshooting

On this page