Troubleshooting
Mounting
exec: "fusermount3": executable file not found — the FUSE helper is not
installed. sudo apt install fuse3 / sudo dnf install fuse3. libfuse3-dev is
headers only and does not help. See Installing
.
fusermount3: mount failed: Operation not permitted — unprivileged FUSE
mounts are disabled, or /dev/fuse is not present. In a container, run it
privileged or pass --device /dev/fuse.
The mountpoint is busy after a crash.
fusermount3 -u ~/drive # Linux
umount -f ~/drive # macOS, FreeBSDOn FreeBSD mount -t fusefs will not list it — the type is fusefs.drivel.
-data is required on this platform — you are on macOS or FreeBSD, where
in-place mode does not exist. Pass a separate backing directory.
A mount hangs and nothing responds. In in-place mode, something read the backing store through the mountpoint path, which recurses into Drivel’s own handler. Nothing in a normal setup does this; it usually means a script or backup tool is pointed at the mounted directory as if it were the backing directory.
unmount … failed: … Device or resource busy (retrying every 1s …).
Something is still using the mountpoint — a shell sitting in it, an editor with
a file open, or a write still being accepted while Drivel shuts down. Drivel
keeps retrying and unmounts the moment it can; fuser -vm MOUNTPOINT shows
what is holding it.
[sync] shutdown deadline (30s): N event(s) never reached an upload worker.
The backend stopped answering while changes were still queued, so Drivel
stopped waiting for it. Nothing is lost: those paths are recorded and the next
start sends them.
state db … was unreadable and has been replaced. The sync-state database was
damaged — typically a power cut mid-write, or a disk going bad. Drivel kept the old
file with .corrupt appended and started with an empty one, which is safe:
nothing is deleted, because a deletion is only ever inferred from a record of
what was previously synced and there are now none.
Expect a full re-enumeration of the remote tree, and a conflict copy of any file whose local and remote copies differ, kept wherever your conflict setting puts losers — with no history, keeping both is the only honest answer. Lazily hydrated files are unaffected. See Data safety .
If this recurs, the disk is the suspect, not Drivel. The .corrupt file is kept
for inspection and is safe to delete.
path index: … was unreadable and has been replaced. The same thing, to the
Drive path index, and with nothing to do about it: that file is purely a cache of
which remote object each path refers to, and every entry is re-checked before use.
Expect a few extra lookups while it warms up.
-lazy needs a backing store that holds user extended attributes. The
backing directory is on a filesystem (exFAT, FAT, some network shares) that cannot
record which files are placeholders, so a lazy mount there could upload an
un-fetched file’s zeros over your remote copy. Drivel refuses rather than risk it.
Mount in eager mode, or move -data to a filesystem with extended attributes. See
lazy mode
.
open state db …: timeout. Another process already has that database open —
almost always a second Drivel still running against the same mount. Check with
pgrep -a drivel. Drivel deliberately does not treat this as damage; replacing
the file would destroy the running mount’s state.
Backends
Drivel runs a backend as a separate process. The two that ship with it are inside the binary, and a backend from anywhere else is an executable Drivel finds and launches — see Installing .
unknown kind: "thing" (available: gdrive, sftp); no drivel-provider-thing in …
— nothing provides that kind. The message lists what is available and every
directory Drivel looked in. Check the spelling in your config file first; if the
backend really is one you meant to add, install drivel-provider-thing into one
of those directories.
unknown kind: "gdrive" (available: sftp), from a Drivel that should have
both — this is a drivel built without its backends (TAGS=nobundle), and it
needs the matching drivel-provider-* executables installed beside it. A
go install …/cmd/drivel@latest build has both inside it.
refusing to run: mode 0777 is writable by everyone — the backend is there,
but anyone on the machine could replace it, and it runs with your credentials.
Fix the permissions rather than working around it:
chmod 755 /usr/local/lib/drivel/plugins/drivel-provider-gdriveThe same message naming a directory means the directory it sits in is world-writable. Move the backend somewhere only you (or root) can write.
backend exited after …; restarting in … — the backend crashed and Drivel is
starting it again. Your mount stays up throughout; pending uploads are retried
once it is back. If it repeats, the lines just above it in the log are the
backend’s own output and are where the reason will be.
Drivel is running a backend you did not expect. A backend built into Drivel
wins over an installed file of the same name, and Drivel names the file it
ignored: plugin gdrive: using the backend bundled in this binary; ignoring /usr/lib/drivel/plugins/drivel-provider-gdrive. Among installed copies the
first on the search path wins, and Drivel logs the other the same way: plugin gdrive: using /usr/bin/drivel-provider-gdrive; also found …. The search order
is: next to the drivel binary, then ~/.local/share/drivel/plugins, then
/usr/local/lib/drivel/plugins, then /usr/lib/drivel/plugins. Setting
DRIVEL_PLUGIN_PATH replaces that list entirely.
Either way the log is the answer, and it is worth reading once after a change: the point of those lines is that “which backend am I running?” is never something you have to work out from a directory listing.
A backend cannot find something it could find when you ran it by hand. Drivel
gives a backend a deliberately small environment — PATH, HOME, TMPDIR,
locale, TLS roots, proxy settings and SSH_AUTH_SOCK — and nothing else. In
particular, ambient cloud credentials (GOOGLE_APPLICATION_CREDENTIALS and its
equivalents) are not passed on: a backend authenticates with what its own
configuration names, so that which account a mount uses is a fact about your
config file and not about the shell you started it from. Put the path in the
config.
Login and credentials
403 access_denied, “app is being tested” — the account you signed in with is
not in the OAuth client’s Test users list. Add it in the Cloud Console, or use
an Internal app type if you have Workspace.
403 accessNotConfigured on Drive calls — the Drive API is not enabled for
the project, or you enabled it in a different project than the OAuth client
belongs to.
redirect_uri_mismatch — the OAuth client is the wrong type. It must be
Desktop app, which permits loopback redirects.
Login worked, then stopped after about a week. Refresh tokens for apps in
Testing status expire after roughly seven days. Re-run drivel login. To
avoid it, publish the app (which adds a Google review) or use an Internal
Workspace app.
The loopback capture never fires (container, headless, remote box) — forward
the port (docker run -p 127.0.0.1:53682:53682 …), or use the paste fallback:
copy the redirect URL out of the browser’s address bar into the prompt. -port 0
picks a free port if 53682 is taken.
drivel mount asks for nothing and fails on credentials. That is deliberate:
mount is non-interactive and never prompts. Run drivel login first.
A credential leaked. Delete the OAuth client in the Cloud Console — that invalidates every token minted from it immediately — and create a new one.
Syncing
Nothing syncs and there are no errors. You are probably in log-only mode: with
no -credentials, Drivel mounts and prints the changes it would sync without
contacting Google. Check the log for [sync] lines that never turn into uploads.
My existing Drive files are not here. In eager mode the first sweep does not
download the whole Drive unless you ask: add -materialize, or use
-lazy
, where the whole tree appears as placeholders for free.
the configured Drive root "…" names nothing this account can see.
-drive-root
(root in a config file)
takes a Drive folder ID, not a folder path and not a folder name. The ID is
the last part of the folder’s address in the Drive web UI — open the folder and
copy the segment after /folders/ in drive.google.com/drive/folders/ID. The
same message appears for a folder belonging to another account, and there are two
near relatives of it for a root that names a file rather than a folder, or one
sitting in the Drive trash. Drivel refuses all four rather than mounting, because
a root it cannot list looks exactly like a Drive where everything was deleted.
Copying many files in starts fast, then the filesystem itself slows down.
Drivel keeps a queue of pending uploads. A bulk copy of many small files can fill
it faster than they upload, and once it is full the filesystem waits rather than
dropping anything — so the copy proceeds at the speed of your uplink. Raising
-push-delay
drains that queue on a
calmer cycle and makes it far less likely. -upload-workers is worth a try for
many small files — until 16 October 2026 the Drive backend uploaded one at a
time no matter what you set, and now it does not — but for anything large the
limit is your uplink and not the pool. A single large file is unaffected: Drivel
notices it once, when it is closed.
Drivel says so when it happens, once each way:
[sync] back-pressure: writes through the mount are now waiting on uploads
(256 of 1280 event(s) queued, 846 awaiting dispatch; -upload-workers 4, -push-delay 300ms)
[sync] back-pressure: cleared after 41m12s — 8104 write(s) waited, 12 event(s) still queuedThose two lines are the whole report, however long the copy runs: they mark the start and the end, not the backlog from moment to moment. Seeing the first without the second means it is still going on.
The first count can be well short of the total — 256 of 1280 above — and that is
not a contradiction. Each file is handled by one of the upload workers, chosen
from its path, so a burst that lands mostly on one worker fills that worker’s
share and stops there while the others still have room. Raising
-upload-workers raises the total, but not the share any one worker gets.
The second count is the rest of the backlog: changes Drivel has accepted from the filesystem and not yet handed to a worker. For a bulk copy that is where almost all of it sits, so it is the number that tells you how much is left.
A file came back after I deleted it. Most likely same-name siblings : the path names more than one Drive object, deleting removed the visible one, and an older one is now visible. Resolve the duplicates in the Drive web UI.
There was a second cause, fixed on 16 October 2026: a file could be re-downloaded seconds after you deleted it, from Drive’s own report of the deletion being still in progress, and the folder it was in then stayed behind for good. If you are on an older build and have an empty folder you deleted, remove it again — and if a sweep has since pushed it back to Drive, remove it there too. See what Drivel does about the race .
A folder I renamed appears twice on my other machines. On Google Drive this
was fixed on 16 October 2026: a rename reaches your other machines as a rename,
and you should see one [pull] move line per rename and no downloads. Before
that, a renamed folder reached them as an empty new folder beside the full old
one; a sweep repaired it for small folders, and for anything over about a hundred
files the repair hit -max-deletes and refused itself, leaving the folder
duplicated for good.
Two cases still take that old route. On SFTP
,
which has no way to report a rename at all. And on Drive, when the machine
receiving the rename has restarted since it last dealt with that folder — no
sweep since it started, and nothing in the folder synced in either direction —
because it then has no record of where the folder used to be. Either way that
machine keeps the old folder until its next sweep, which downloads the new one in
full and deletes the old one, unless the old one holds more files than
-max-deletes: then the delete is refused and the folder stays doubled.
To repair a doubled folder, delete the stale copy through the mount — it is the
one whose files are no longer on the remote — then re-run with -resync and a
-max-deletes above the number of files involved (or 0), which is the same
recipe as the refusal below.
[sweep] REFUSING to delete: … over the -max-deletes limit. Drivel inferred more
deletions than the cap allows and abandoned the entire pass rather than performing
part of it. Check first that the mount is pointed where you think it is — a wrong
-drive-root, or an empty -data, produces exactly this. A renamed folder that
took the old route is the other common cause, and the entry above has the recipe. If the
deletions are genuine, re-run with both -resync and a higher
-max-deletes; the cap alone changes nothing until the next scheduled sweep.
[sync] push write … failed after 5 attempt(s). Drivel tried, backed off
between attempts, and gave up — a few seconds of retries in total. A
non-retryable error (a permission failure, a quota refusal) gives up after the
first attempt instead, which the count tells you. The file on your machine is
fine; it is the copy on the remote that is now behind.
The line ends in (recorded for repair by the next sweep), and that is what
happens: Drivel remembers the path and re-sends it from the next enumeration,
which it schedules within a few minutes rather than waiting for
-sweep-interval
. This works
with -sweep-interval 0 too — 0 means “do not poll”, not “never repair”. You
will see the repair in the log as [sweep] repush PATH (an earlier push was abandoned), and the sweep’s closing summary counts them.
If the failures keep coming, fix the cause rather than waiting: the repair is re-attempted on a sweep that backs off as it keeps failing, out to 80 minutes between tries, so it will not fix a wrong credential or a full account for you.
Drivel was killed while uploading, and the file never went up. It does now, on
the next start: a mount that did not shut down cleanly sweeps when it comes back
up ([sweep] the run started at … did not shut down cleanly). Drivel records the size and timestamp of every file at the moment
it syncs it, and a sweep re-sends anything whose local copy no longer matches:
[sweep] repush notes/todo.md (local copy diverged from its baseline; an earlier push never landed)Before this it did not, and the reason is worth knowing because it explains why waiting did not help: a sweep compares the remote against what Drivel last recorded, the crash left both of those agreeing, and the only thing that had changed was your local file — which nothing was looking at. Sweeping repeatedly could not fix it.
The bounds are in configuration
,
and the one that decides what to do here is that only files modified before the
mount started are considered: this is repair for what happened while Drivel was
down, not a second uploader running beside the first. So if you suspect a file is
still behind, restart the mount — or run -resync to sweep without waiting.
A file I deleted is still on the remote. A deletion that could not be sent
is retried by a sweep about five minutes later, and so is a file deleted from the
backing directory while Drivel was not running — though after a clean shutdown
that one waits for the next scheduled sweep, so run -resync to have it picked
up at once. Look in the sweep’s log for the path. delete … remotely means it
went. keep … remotely (… changed remotely …) means somebody edited it after you
last synced, and the edit won over your deletion — it is downloaded here again.
keep … remotely (… holds …) on a folder names something inside it that Drivel
never synced, which keeps the folder. A REFUSING to delete line means the
sweep wanted more deletions than -max-deletes
allows; see above.
[pull] apply PATH: … — a remote change did not arrive. The download or
the local write failed. Drivel retries it on its own about a minute later
([pull] refetch PATH), then less and less often if it keeps failing, out to
about an hour, so a cause that does not clear on its own — a full disk, a name
the backing filesystem will not accept — needs fixing, and the next retry then
succeeds. drivel status PATH shows such a file as error until it does. See
when a download fails
.
Inbound sync stopped silently. Google expires change cursors. Drivel
recognises the expiry and recovers by re-enumerating; if you suspect it has not,
-resync forces the sweep.
A file is empty that should not be. If you are running -lazy, check that the
backing filesystem supports extended attributes — this is the failure mode that
rule exists to prevent. See lazy mode
.
ln: failed to create hard link: Operation not permitted. Deliberate. Drivel
refuses hard links because no cloud store it can talk to represents them, and
permitting one produced two files that silently diverged. Symlinks work; see
data safety
.
A symlink, FIFO or socket is not appearing on my other machines. It never
will. Those have no content to upload and no representation on Drive, so they stay
in the backing directory on the machine that made them. Drivel logs a
skip … no remote representation, stays local line for each one, from the mount
and from the sweep. On FreeBSD, creating a FIFO on the mount fails outright with
EINVAL, while symlinks work normally — see
platforms
.
A file was deleted and you want it back. Deletions go to the Drive trash, so
look in drive.google.com
and restore it
there; it comes back down to your machines as an ordinary change. Drive purges the
trash after 30 days, and -drive-delete permanent skips it entirely — with that
set there is nothing to recover from. If a sweep deleted more than you expected,
read data safety
before re-mounting: the same premise
that produced the first pass will produce the second.
Everything is slow to appear. Inbound changes arrive by polling, on an adaptive interval: about every 2 seconds while the feed is active, backing off toward 30 seconds once it goes quiet. There is no push channel — Drivel follows Drive’s change-feed cursor, not webhooks — so a first change after an idle period can take up to half a minute to show up.
Quota and cost
The sweep is expensive on a large account. If you mount a folder rather than
the whole Drive, make sure the sweep is descending it rather than listing the
account: -drive-sweep-mode scoped. See
configuration
.
Deleting files does not free space. Deletions go to the Drive trash by
default, and a trashed file counts against your quota until the trash is emptied.
Empty it from the web UI, or run the mount with -drive-delete permanent if
reclaiming space as you delete matters more to you than being able to undo one.
The same file is uploaded again and again. Drivel uploads a file once it has
gone -push-delay
without changing,
300ms by default, so a file written repeatedly — an editor autosaving, a log, a
build artefact — is uploaded once per save. Raising the delay coalesces those into
one upload per window. Note that a file which is appended to is re-uploaded
whole each time on backends that cannot patch byte ranges, Drive among them, so
the saving here can be large.
Several mounts of one account each poll the whole change feed. Drive’s change feed has no folder filter, so this is inherent, not a misconfiguration. It costs quota, not latency.
Getting more detail
drivel mount … -debug # FUSE-level tracing: every call in and out
drivel mount … -pprof localhost:6060 # Go profiling endpoints-debug is extremely verbose but is the fastest way to see what the kernel is
actually asking for. -pprof serves the process heap — which holds synced paths
and buffered content — so bind it to loopback only.
If you are filing a bug, the useful attachments are the log around the failure,
the flags or config block, the backing filesystem type (stat -f -c %T DIR), and
whether -lazy was on.