Skip to main content

Troubleshooting

Cleanr opens, but nothing is scanned​

This is expected. Startup only sets the scan roots. Press s, run /scan, or press u for a usage scan.

The command palette does not show /review or /clean​

Commands that require scan results stay hidden until a scan finishes. Run /scan first. If a scan is still active, wait for it to finish or cancel it with Esc or x.

A scan finds no candidates​

Check the following:

  • The relevant pack is listed in cleanup.enabled_rule_packs.
  • The target is not excluded by ignore_dirs or ignore_patterns.
  • The item meets the rule's size, age, name, or path requirements.
  • The item meets the effective [recommendations].preselect_after_days modification-age threshold. cleanr analyze retains below-threshold evidence; if that confirms a rule match, adjust the setting or rerun with an intentional /scan --inactive-days <DAYS> override.
  • You scanned the directory that contains the candidate, not the candidate directory as the root. Scan roots themselves are never cleanup candidates.

Use /rules to inspect loaded rules and /plugins to confirm custom bundles were discovered.

/scan --global says no cleanup locations were found​

The current platform did not report any known user-level system cleanup locations for the selected global categories. You can still provide paths explicitly:

/scan /home/me/.cargo /home/me/.npm

Use absolute paths that exist on your operating system. Paths entered in the TUI do not expand ~ or environment variables.

Cleanr reports a configuration parse error​

Print the active default path:

cleanr config path

If you use a custom file, repeat the same --config option when diagnosing. Look for unknown keys, misspelled enum values, duplicate IDs, or invalid TOML.

To compare with a fresh default without overwriting your file:

cleanr --config /tmp/cleanr-default.toml config init

The terminal display is unreadable​

  • Make sure the terminal supports Unicode and color.

  • Cleanr uses portable ANSI colors by default. If colors still appear as solid red/green blocks, reset the terminal profile or try another terminal app.

  • If the background brightness is wrong, set an explicit theme:

    cleanr config set ui.theme dark

  • Resize very small terminal windows.

  • If Cleanr is interrupted, run reset in the shell to restore terminal state.

Cleanup skips an item that was selected​

Cleanr revalidates every target immediately before execution. The item is skipped if it changed after scanning, became a symbolic link, moved outside a scan root, or overlaps a protected path. Rescan and review the new state rather than forcing the old plan.

Restore fails​

Common causes are:

  • the system trash was emptied;
  • the item was manually removed from trash;
  • the original path now exists;
  • trash metadata changed or is unavailable;
  • programmatic restore is unsupported by the platform.

Cleanr does not overwrite the current path. Inspect the system trash manually and preserve Cleanr's state directory and manifests while investigating.

Disable the update check​

Cleanr checks for a new release at most once every 24 hours. Disable the non-blocking startup check with:

Cleanr 0.16.0 and later check in a background worker with a 10-second HTTP timeout. The first screen does not wait for the network. A new-version notice appears separately on Home and does not replace task errors.

cleanr --no-update-check

or:

export CLEANR_NO_UPDATE_CHECK=true

A global scan is slow or appears stuck​

Opt into the scan budgets described in Configuration to bound retained entries, elapsed time, estimated allocation, or retained diagnostics. Enabled budgets use one traversal worker and return read-only partial evidence when reached. An elapsed limit is cooperative: it is checked between scan phases and filesystem operations, but cannot interrupt a metadata or directory read already blocked in the operating system kernel. Cancel the scan if the kernel call eventually returns; investigate the filesystem, mount, or network share if it repeatedly blocks.

Installation, update, or removal problems​

Follow Quick start for the OS/CPU asset mapping and update, rollback, and uninstall commands. Check command -v cleanr on macOS/Linux or Get-Command cleanr in PowerShell if the version did not change. Multiple installation methods can leave more than one executable on your PATH.

The cleanup total did not become free disk space​

Moving items to system Trash usually leaves their disk blocks allocated. The candidate or moved-byte total is not a free-space measurement. Cleanr keeps recovery possible while the Trash item and local record exist; emptying Trash is a separate decision and removes that recovery source.

Get more help​

If the problem is reproducible, open an issue on GitHub with:

  • your Cleanr version (cleanr --version);
  • operating system and terminal;
  • installation method;
  • the exact command or key sequence;
  • the complete error message with secrets and personal paths removed.

Use the support forms for installation, rule matching, or recovery issues. Do not attach raw analysis JSON, plans, or manifests. Suspected security problems belong in private reporting.