Troubleshooting

Common issues and how to resolve them.

To debug issues with Fring, start by checking the logs and local data it stores on disk.

Logs

Log files are written to:

macOS/Linux: ~/.local/share/fring/log/
Windows: Press WIN+R and paste %USERPROFILE%\.local\share\fring\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, fring --log-level DEBUG.

Storage

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

macOS/Linux: ~/.local/share/fring/
Windows: Press WIN+R and paste %USERPROFILE%\.local\share\fring

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/

Desktop app

Fring Desktop runs a local Fring server (the opencode-cli sidecar) in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.

Quick checks

Fully quit and relaunch the app.
If the app shows an error screen, click Restart and copy the error details.
macOS only: Fring menu -> Reload Webview (helps if the UI is blank/frozen).

Disable plugins

If the desktop app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.

Check the global config

Open your global config file and look for a plugin key.

macOS/Linux: ~/.config/fring/fring.jsonc (or ~/.config/fring/fring.json)
macOS/Linux (older installs): ~/.local/share/fring/fring.jsonc
Windows: Press WIN+R and paste %USERPROFILE%\.config\fring\fring.jsonc

If you have plugins configured, temporarily disable them by removing the key or setting it to an empty array:

{
  "$schema": "https://fring.ai/config.json",
  "plugin": [],
}

Check plugin directories

Fring can also load local plugins from disk. Temporarily move these out of the way (or rename the folder) and restart the desktop app:

Global plugins
- macOS/Linux: ~/.config/fring/plugins/
- Windows: Press WIN+R and paste %USERPROFILE%\.config\fring\plugins
Project plugins (only if you use per-project config)
- <your-project>/.opencode/plugins/

If the app starts working again, re-enable plugins one at a time to find which one is causing the issue.

Clear the cache

If disabling plugins doesn’t help (or a plugin install is stuck), clear the cache so Fring can rebuild it.

Quit Fring Desktop completely.
Delete the cache directory:

macOS: Finder -> Cmd+Shift+G -> paste ~/.cache/fring
Linux: delete ~/.cache/fring (or run rm -rf ~/.cache/fring)
Windows: Press WIN+R and paste %USERPROFILE%\.cache\fring

Restart Fring Desktop.

Fix server connection issues

Fring Desktop can either start its own local server (default) or connect to a server URL you configured.

If you see a “Connection Failed” dialog (or the app never gets past the splash screen), check for a custom server URL.

Clear the desktop default server URL

From the Home screen, click the server name (with the status dot) to open the Server picker. In the Default server section, click Clear.

Remove `server.port` / `server.hostname` from your config

If your opencode.json(c) contains a server section, temporarily remove it and restart the desktop app.

Check environment variables

If you have OPENCODE_PORT set in your environment, the desktop app will try to use that port for the local server.

Unset OPENCODE_PORT (or pick a free port) and restart.

Linux: Wayland / X11 issues

On Linux, some Wayland setups can cause blank windows or compositor errors.

If you’re on Wayland and the app is blank/crashing, try launching with OC_ALLOW_WAYLAND=1.
If that makes things worse, remove it and try launching under an X11 session instead.

Windows: WebView2 runtime

On Windows, Fring Desktop requires the Microsoft Edge WebView2 Runtime. If the app opens to a blank window or won’t start, install/update WebView2 and try again.

Windows: General performance issues

If you’re experiencing slow performance, file access issues, or terminal problems on Windows, try using WSL (Windows Subsystem for Linux). WSL provides a Linux environment that works more seamlessly with Fring’s features.

Notifications not showing

Fring Desktop only shows system notifications when:

notifications are enabled for Fring in your OS settings, and
the app window is not focused.

Reset desktop app storage (last resort)

If the app won’t start and you can’t clear settings from inside the UI, reset the desktop app’s saved state.

Quit Fring Desktop.
Find and delete these files (they live in the Fring Desktop app data directory):

fring.settings.dat (desktop default server URL)
fring.global.dat and fring.workspace.*.dat (UI state like recent servers/projects)

To find the directory quickly:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (then search for the filenames above)
Linux: search under ~/.local/share for the filenames above
Windows: Press WIN+R -> %APPDATA% (then search for the filenames above)

Getting help

If you’re experiencing issues with Fring:

Email support

The fastest way to reach us about a bug, a billing question or a feature request:

support@fring.ai

Include your Fring version (fring --version) and, where relevant, the output of fring --print-logs.

Common issues

Here are some common issues and how to resolve them.

Fring 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 fring upgrade

Authentication issues

Try re-authenticating with the /connect command in the TUI
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

If you encounter ProviderModelNotFoundError you are most likely incorrectly referencing a model somewhere. Models should be referenced like so: <providerId>/<modelId>

Examples:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

To figure out what models you have access to, run fring models

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/fring
```
On Windows, press WIN+R and delete: %USERPROFILE%\.local\share\fring
Re-authenticate with your provider using the /connect command in the TUI.

AI_APICallError and provider package issues

If you encounter API call errors, this may be due to outdated provider packages. Fring 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/fring
```
On Windows, press WIN+R and delete: %USERPROFILE%\.cache\fring
Restart Fring to reinstall the latest provider packages

This will force Fring 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

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