Troubleshooting

Common issues and how to resolve them.

To debug any issues with codeflow, you can check the logs or the session data that it stores locally.

Logs

Log files are written to:

macOS/Linux: ~/.local/share/codeflow/log/
Windows: %APPDATA%\codeflow\log\

Log files are named with timestamps (e.g., 2025-01-09T123456.log) and the most recent 10 log files are kept.

You can configure the log level in your config file to get more detailed debug information.

Storage

codeflow stores session data and other application data on disk at:

macOS/Linux: ~/.local/share/codeflow/
Windows: %USERPROFILE%\.local\share\codeflow

This directory contains:

auth.json - Authentication data like API keys, OAuth tokens
log/ - Application logs
project/ - Project-specific data like session and message data
- If the project is within a Git repo, it is stored in ./<project-slug>/storage/
- If it is not a Git repo, it is stored in ./global/storage/

Common issues

Here are some common issues and how to resolve them.

codeflow won’t start

Check the logs for error messages
Try running with --print-logs to see output in the terminal
Ensure you have the latest version with codeflow upgrade

Authentication issues

Try re-authenticating with codeflow auth login <provider>
Check that your API keys are valid
Ensure your network allows connections to the provider’s API

Model not available

Check that you’ve authenticated with the provider
Verify the model name in your config is correct
Some models may require specific access or subscriptions

ProviderInitError

If you encounter a ProviderInitError, you likely have an invalid or corrupted configuration.

To resolve this:

First, verify your provider is set up correctly by following the providers guide
If the issue persists, try clearing your stored configuration:
Terminal window
```
rm -rf ~/.local/share/codeflow
```
Re-authenticate with your provider:
Terminal window
```
codeflow auth login <provider>
```

AI_APICallError and provider package issues

If you encounter API call errors, this may be due to outdated provider packages. codeflow dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.

To resolve provider package issues:

Clear the provider package cache:
Terminal window
```
rm -rf ~/.cache/codeflow
```
Restart codeflow to reinstall the latest provider packages

This will force codeflow to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.

Copy/paste not working on Linux

Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:

For X11 systems:

apt install -y xclip
# or
apt install -y xsel

For Wayland systems:

apt install -y wl-clipboard

For headless environments:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

codeflow will detect if you’re using Wayland and prefer wl-clipboard, otherwise it will try to find clipboard tools in order of: xclip and xsel.