Skip to main content

Troubleshooting

Symptom → cause → fix. Run the verify command first; if it matches, apply the fix.

If you have lost data rather than hit an error, go to Recovery instead.

REFUSE: protected path​

✗ REFUSE: protected path: /home/you/Documents/something

Cause. The path resolved — after symlink expansion — to somewhere on the protected list. The allowlist blocked it.

This is correct behaviour, not a failure. Nothing was deleted.

Fix. Find out what resolved where:

linux-cleanup --list-targets
realpath <the path that was rejected>

Almost always a cache symlinked into a protected directory. Fix the symlink, not the tool — the tool is doing exactly its job. There is no override flag, by design.

Two related messages:

✗ REFUSE: unsafe path: '/home/you' # bare $HOME or /
✗ REFUSE: shell-init / history file: … # .bashrc, .zshrc and similar

TUI mode needs whiptail or dialog​

Cause. --tui was run with neither installed.

Fix. Install one, or accept the offered fallback to the CLI menu.

sudo apt install whiptail # Debian / Ubuntu
sudo dnf install newt # Fedora / RHEL
sudo pacman -S libnewt # Arch

Verify. command -v whiptail, then re-run. See TUI.

export requires jq​

Cause. --export md, --export html, or a conversion in the reports manager, without jq installed.

Fix.

sudo apt install jq

jq is needed only for conversion. JSON records are still written on every run without it. See Reports.

command not found​

Cause. A required dependency is missing or shadowed by an incompatible alias. Common on minimal containers that ship BusyBox instead of GNU coreutils.

Verify.

linux-cleanup --self-test

This probes every required command and names the first one missing.

Fix. Install your distro's coreutils, findutils and gawk packages. On Alpine:

apk add coreutils findutils bash

realpath matters most — it is what makes the protected-path check symlink-safe. See Distro support.

Cron entry runs but does nothing​

Verify.

tail -100 ~/.linux-cleanup/logs/cron.log
crontab -l | grep -i cleanup

Cause. command not found in the cron log means cron's minimal PATH (/usr/bin:/bin) cannot see your install. This is the single most common cron problem.

Fix. Use an absolute path in the crontab:

crontab -e
# Change: 0 3 * * 0 linux-cleanup --all-safe -y …
# To: 0 3 * * 0 /usr/local/bin/linux-cleanup --all-safe -y …

Find the right path with command -v linux-cleanup. Alternatively put a PATH= line at the top of the crontab. See Alias and cron.

$HOME is not set​

✗ $HOME is not set

Cause. Running in a context that does not set $HOME — some Docker images, some CI runners.

Fix.

HOME=/root linux-cleanup --scan

Or export it once for the session. The script aborts rather than guessing, deliberately: a wrong $HOME would mean every path check is evaluated against the wrong tree.

Scan or --node-modules seems to hang​

Cause. find walking thousands of directories under $HOME. On a spinning disk the first run takes one to three minutes.

Verify. Watch the log rather than the terminal:

tail -f ~/.linux-cleanup/logs/cleanup-*.log

New lines every five to ten seconds means it is working.

Fix. Be patient on the first run; later runs are faster thanks to cached directory metadata. If the same path consistently stalls past five minutes, suspect a symlink loop or an unresponsive network or FUSE mount — and report it.

Disk usage grew during the session​

Cause. The reported recovery is a df delta across the whole machine. Another process — a build, a package update, journal rotation, an IDE re-indexing — wrote more during your session than the cleanup reclaimed.

This is not a bug, and it does not mean the cleanup failed. Check what the steps themselves reported:

jq '.steps[] | select(.status == "ran") | {title, freed_bytes}' \
"$(ls -t ~/.linux-cleanup/reports/report-*.json | head -1)"

Fix. Re-run --scan when the machine is quiet to see the real picture.

apt update fails after --system​

Cause. Rare. apt clean does not break apt update, but the cleanup may have raced with another apt operation holding a lock.

Verify.

sudo apt update 2>&1 | tail -20

Fix.

sudo rm -f /var/lib/apt/lists/lock /var/cache/apt/archives/lock /var/lib/dpkg/lock-frontend
sudo apt update

Do this only when no apt process is genuinely running — ps aux | grep -i apt first.

VS Code reports a missing extension​

Cause. Usually correct behaviour: a superseded version was removed while the editor still held a reference to it.

Fix. Reload the window — Ctrl+Shift+P → Developer: Reload Window.

Verify the current version is still present:

ls ~/.vscode/extensions/ | grep <extension-name>

If the current version is genuinely gone, that indicates a bug in the highest-version detection. Reinstall and report it:

code --install-extension <publisher>.<name>

A crash bundle appeared but I saw no crash​

Cause. The script exited non-zero from somewhere unexpected — a backgrounded find killed by the OOM killer, or a broken pipe.

Fix. Read the exit code in the bundle's manifest:

tar -xzOf ~/.linux-cleanup/feedback/crash-*.tar.gz --wildcards '*MANIFEST*'

137 is the OOM killer, 141 is SIGPIPE, 139 a segfault. See Exit codes. Any of these is worth reporting.

alias cleanup: not found after --install-alias​

Cause. The shell rc file has not been re-read.

Fix.

source ~/.bashrc # or ~/.zshrc

Or open a new terminal.

Wrong version running​

Verify.

command -v linux-cleanup
linux-cleanup --version

Cause. An old global install shadowing a newer npx cache, or a stale shell command hash.

Fix.

npm uninstall -g linux-cleanup
npm install -g linux-cleanup@latest
hash -r
linux-cleanup --version

Check the npm package for the current published version. Review the changelog for changes since your installed copy.

Still stuck​

linux-cleanup --debug-bundle
linux-cleanup --feedback

Review the bundle, then email it with a short description of expected versus actual. See Send a bug report.