Dropstone Docs

Troubleshooting

Common issues and how to resolve them.

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

Logs

Log files are written to:

  • macOS / Linux: ~/.local/share/dropstone/log/
  • Windows: press WIN+R and paste %USERPROFILE%\.local\share\dropstone\log

Log files are named with timestamps (for example 2026-05-23T123456.log) and the most recent 10 log files are kept.

You can set the log level with the --log-level command-line option for more detailed debug output:

dropstone --log-level DEBUG

--print-logs also streams logs to stderr in real time:

dropstone --print-logs

Storage

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

  • macOS / Linux: ~/.local/share/dropstone/
  • Windows: press WIN+R and paste %USERPROFILE%\.local\share\dropstone

This directory contains:

  • auth.json: Authentication credentials
  • log/: Application logs
  • project/: Project-specific data like session history
    • If the project is inside a Git repo, it is stored in ./<project-slug>/storage/
    • Otherwise it is stored in ./global/storage/

Common issues

Dropstone won't start

  1. Check the logs for an error message.
  2. Try running with --print-logs to stream logs to stderr.
  3. Ensure you are on the latest version: dropstone update.

Authentication issues

If sign-in or token validation fails:

  1. Re-run dropstone and sign in again through the browser flow.
  2. If you are in a headless environment, set DROPSTONE_API_KEY from a token issued at dropstone.io/account.
  3. Confirm your network allows outbound HTTPS to dropstone.io. If you are behind a corporate proxy, see Network.

Model not found

If you see ModelNotFoundError, you are likely referencing a model ID that doesn't exist. Use one of:

  • dropstone/dropstone-fast
  • dropstone/dropstone-pro
  • dropstone/dropstone-heavy

Run dropstone models to confirm what's available to your account.

Initialisation error

If you see an InitError on launch, your stored credentials may be invalid or corrupted.

  1. Clear your stored data:

    rm -rf ~/.local/share/dropstone

    On Windows: press WIN+R and delete %USERPROFILE%\.local\share\dropstone.

  2. Re-run dropstone and sign in again.

API call errors

If you see API call errors during a session, the on-disk cache may be stale.

  1. Clear the cache:

    rm -rf ~/.cache/dropstone

    On Windows: press WIN+R and delete %USERPROFILE%\.cache\dropstone.

  2. Restart Dropstone.

Copy / paste not working on Linux

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

X11

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

Wayland

apt install -y wl-clipboard

Headless

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

Dropstone prefers wl-clipboard on Wayland and falls back to xclip then xsel on X11.

Windows: General performance issues

If you are seeing slow performance, file-access problems, or terminal glitches on native Windows, switch to WSL. WSL gives you a Linux environment that runs Dropstone with native filesystem speed and full terminal support.

Getting help

Ctrl+I