mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-25 03:34:22 +01:00
157 lines
3.9 KiB
Plaintext
157 lines
3.9 KiB
Plaintext
---
|
|
title: Troubleshooting
|
|
description: Common issues and how to resolve them.
|
|
---
|
|
|
|
To debug any issues with opencode, you can check the logs or the session data
|
|
that it stores locally.
|
|
|
|
---
|
|
|
|
### Logs
|
|
|
|
Log files are written to:
|
|
|
|
- **macOS/Linux**: `~/.local/share/opencode/log/`
|
|
- **Windows**: `%USERPROFILE%\.local\share\opencode\log\`
|
|
|
|
Log files are named with timestamps (e.g., `2025-01-09T123456.log`) and the most recent 10 log files are kept.
|
|
|
|
You can set the log level with the `--log-level` command-line option to get more detailed debug information. For example, `opencode --log-level DEBUG`.
|
|
|
|
---
|
|
|
|
### Storage
|
|
|
|
opencode stores session data and other application data on disk at:
|
|
|
|
- **macOS/Linux**: `~/.local/share/opencode/`
|
|
- **Windows**: `%USERPROFILE%\.local\share\opencode`
|
|
|
|
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/`
|
|
|
|
---
|
|
|
|
## Getting help
|
|
|
|
If you're experiencing issues with opencode:
|
|
|
|
1. **Report issues on GitHub**
|
|
|
|
The best way to report bugs or request features is through our GitHub repository:
|
|
|
|
[**github.com/sst/opencode/issues**](https://github.com/sst/opencode/issues)
|
|
|
|
Before creating a new issue, search existing issues to see if your problem has already been reported.
|
|
|
|
2. **Join our Discord**
|
|
|
|
For real-time help and community discussion, join our Discord server:
|
|
|
|
[**opencode.ai/discord**](https://opencode.ai/discord)
|
|
|
|
---
|
|
|
|
## Common issues
|
|
|
|
Here are some common issues and how to resolve them.
|
|
|
|
---
|
|
|
|
### opencode won't start
|
|
|
|
1. Check the logs for error messages
|
|
2. Try running with `--print-logs` to see output in the terminal
|
|
3. Ensure you have the latest version with `opencode upgrade`
|
|
|
|
---
|
|
|
|
### Authentication issues
|
|
|
|
1. Try re-authenticating with `opencode auth login <provider>`
|
|
2. Check that your API keys are valid
|
|
3. Ensure your network allows connections to the provider's API
|
|
|
|
---
|
|
|
|
### Model not available
|
|
|
|
1. Check that you've authenticated with the provider
|
|
2. Verify the model name in your config is correct
|
|
3. 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:
|
|
|
|
1. First, verify your provider is set up correctly by following the [providers guide](/docs/providers)
|
|
2. If the issue persists, try clearing your stored configuration:
|
|
|
|
```bash
|
|
rm -rf ~/.local/share/opencode
|
|
```
|
|
|
|
3. Re-authenticate with your provider:
|
|
```bash
|
|
opencode auth login <provider>
|
|
```
|
|
|
|
---
|
|
|
|
### AI_APICallError and provider package issues
|
|
|
|
If you encounter API call errors, this may be due to outdated provider packages. opencode dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.
|
|
|
|
To resolve provider package issues:
|
|
|
|
1. Clear the provider package cache:
|
|
|
|
```bash
|
|
rm -rf ~/.cache/opencode
|
|
```
|
|
|
|
2. Restart opencode to reinstall the latest provider packages
|
|
|
|
This will force opencode 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:**
|
|
|
|
```bash
|
|
apt install -y xclip
|
|
# or
|
|
apt install -y xsel
|
|
```
|
|
|
|
**For Wayland systems:**
|
|
|
|
```bash
|
|
apt install -y wl-clipboard
|
|
```
|
|
|
|
**For headless environments:**
|
|
|
|
```bash
|
|
apt install -y xvfb
|
|
# and run:
|
|
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
|
|
export DISPLAY=:99.0
|
|
```
|
|
|
|
opencode 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`.
|