Dropstone CLI

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.

If it dies instantly with nothing printed at all on macOS, that is a different failure — see Killed on launch on macOS.

Killed on launch on macOS

On Apple Silicon, Dropstone 1.0.50 was killed by macOS before it printed anything, so every command looked like this:

dropstone --version
# zsh: killed     dropstone --version

There is no log to read and no error to search for: the process is stopped before it starts, which is why --print-logs and dropstone upgrade are killed as well. macOS validates the signature on the binary before running it, and the one stamped into that build did not match. macOS up to 26 tolerated it; macOS 27 does not. Windows and Linux were never affected.

To confirm it before reinstalling:

codesign --verify --verbose=4 "$(readlink -f "$(which dropstone)")"
# /opt/homebrew/bin/dropstone: invalid signature (code or signature have been modified)

Then replace the binary. Homebrew and the installer both work without the installed copy running:

# Homebrew
brew update && brew upgrade dropstone

# The one-line installer
curl -fsSL https://dropstone.io/install.sh | bash

To unblock the copy you already have instead of reinstalling:

codesign --force --sign - "$(readlink -f "$(which dropstone)")"

1.0.51 and later are signed in a way macOS accepts, and every release checks that signature before it is published.

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