Troubleshooting
Fixes for common 1FileTool problems: installer warnings, failed runs, OCR and model downloads, the daily limit, license activation and AI Chat.
Most 1FileTool problems come down to the installer, a blocked first download, or Replace source doing exactly what it says — work through the section that matches your symptom.
Installing and updating
Windows says "Windows protected your PC" (SmartScreen). The Windows installer isn't code-signed yet, so SmartScreen flags it on first launch. Choose More info → Run anyway — the download came from the official release. (macOS builds are signed and notarized; this warning is Windows-only.)
The AppImage won't launch on Linux. Make it executable (chmod +x), and if your distro lacks FUSE, either install libfuse2/fuse or run it with --appimage-extract-and-run. Linux builds are unsigned — package managers may warn on the .deb too.
No ARM build on Windows or Linux. The app ships ARM builds for Apple Silicon only; x64 Windows and Linux are supported.
Updates: use Check for Updates... in the app menu (macOS) or the File menu (Windows/Linux). The app also checks GitHub Releases every 6 hours by itself; manage that in Settings › Updates.
Running tools
Protect your originals first
Replace source is ON by default: the output overwrites the original file and no backup is kept. Before following along, open Settings › General and turn Replace source off, or pick a separate output folder.
I can't find my result. Check the result card after the run, then History — every run is recorded. If Replace source was on, the output is the original file (overwritten in place); if it was off, look in ~/Documents/1FileTool or the folder you picked with Change.
The tool failed with an error message. The result card shows the error text; copy it before retrying. Common causes: the input format isn't supported by that tool (e.g. HEIC is input-only — you can't convert to HEIC), a corrupted source file, or the file is locked by another app.
The output file is bigger than the original. That happens legitimately — some sources (already-optimized files, low-quality JPEGs re-encoded as PNG) can't shrink. The result card always shows size before/after so nothing is hidden.
OCR came out garbled or empty. Tesseract.js is English-only and writes a .txt file, not a searchable PDF; handwriting and low-resolution scans won't read well.
An AI feature asked to download a model. Expected — first use of a voice (~63 MB from Hugging Face) or Background Removal (~178 MB from GitHub) downloads a model once. If it stalls, check your connection and retry; after the download it works offline.
Limits and license
"Daily limit reached — resets tomorrow". The free tier counts 8 output files per calendar day; the sidebar counter shows where you stand. Pro removes the cap — see Free vs Pro.
License activation failed. Re-paste the full key in Settings › License, check you're within the device limit (1/3/5), and deactivate an old device from the same tab before retrying. Activation needs network access to Lemon Squeezy.
AI Chat
AI Chat isn't working. It's a bridge to an AI CLI you've installed yourself (Claude Code, Gemini CLI, Codex and friends) — the CLI must be installed and signed in, and the model provider sees whatever it reads. Auto-setup covers Claude Code and Gemini CLI; other CLIs need manual setup. If nothing responds, open a terminal and check the CLI runs standalone first.