Troubleshooting
Fixes for the most common NameQuick issues - permissions, renames not running, provider errors, renames and trial questions, and where to find logs.
Most issues fall into one of four buckets: macOS permissions, AI provider configuration, renames/licensing, or a folder that isn't being watched. Find your symptom below — and if nothing here helps, Export Diagnostics and email us.
Files aren't being renamed#
The watch folder isn't active. Check the folder's watching state in the sidebar — it must show as watching, with Auto enabled for automatic processing. See Watch Folders.
NameQuick can't access the folder. macOS requires you to grant folder access explicitly. Re-add the folder via the + button so macOS shows the permission prompt again, or check System Settings → Privacy & Security → Files and Folders.
The file type isn't supported. Check Supported File Formats — NameQuick covers 30+ formats, but not everything.
You're in review mode. Names may be waiting for your approval rather than failing. Open the app and check the To Process view — see Rename Modes.
Permission problems#
"macOS blocked the helper" (launch at login): open System Settings → Login Items, allow NameQuick in the background, then try again — the in-app message walks you through it.
Finder Automation: NameQuick asks for Finder automation permission so renames apply instantly. If you declined it once, re-enable it under System Settings → Privacy & Security → Automation → NameQuick.
Notifications: if you're not seeing batch-completion notifications, allow NameQuick under System Settings → Notifications.
AI provider errors#
"Add your API key in Settings → AI" — the selected provider has no key. Add one (guide) or switch to Managed or a local model.
Renames fail with a valid key — usually the provider account lacks billing credit. Check the provider's billing dashboard; a key without credit behind it can't be used.
Rate limit / quota errors — the provider is throttling you. Smaller batches help; new accounts get higher limits automatically after a few days.
"Vision model missing" for images or scanned PDFs — your local model is text-only. Pull a vision-capable model and select it in Settings → AI (local models guide).
Keychain locked or unavailable — NameQuick stores keys in the macOS Keychain. Unlock your Mac's keychain (it normally unlocks with login) and retry.
Local model unreachable — make sure Ollama or LM Studio's server is actually running and the address in Settings → AI matches (http://127.0.0.1:11434 for Ollama, localhost:1234 for LM Studio).
Renames, trial & license#
Full operational detail — activation, moving Macs, what consumes a rename — lives in License, Trial & Renames.
Trial exhausted — the Self-Managed trial includes 50 renames; the Managed trial includes 250 renames over 14 days, whichever runs out first. When it ends, pick a plan in Settings → Usage or on the pricing page: Managed renames from $12/month, or the $69 one-time Self-Managed license with your own key or a local model.
Out of renames (Managed) — your monthly renames ran out. Settings → Usage shows your balance and renewal date; you can upgrade tiers anytime, and unused renames carry into the next month.
License won't validate offline — NameQuick has offline grace periods, so short offline stretches are fine. If validation keeps failing online, check the system clock and any VPN/firewall, then contact support with diagnostics.
OCR and quality issues#
Scanned PDFs get generic names — very low-resolution scans give OCR little to work with. Re-scan at 300 DPI where possible.
Names are in the wrong language — set your preferred output language in settings; NameQuick supports multilingual naming.
A name came out wrong — every rename is reversible. Find the file in the Library's Processed view and revert it; original timestamps are untouched either way.
Get help#
- Export Diagnostics from the app menu and attach it to your email — it contains logs, not your file contents.
- Show Logs if you want to look yourself first.
- Email support@namequick.app — include your macOS version and what you expected vs. what happened. Real human, usually fast.
- Feature ideas and roadmap: namequick.featurebase.app/roadmap.
Related guides
AI File Renaming on Mac: How It Works + 6 Tools Compared (2026)
We tested 6 AI file renaming tools for macOS. See how OCR and AI turn cryptic file names like IMG_4823.jpg into organized, searchable names automatically.
How to Rename a File on Windows, Mac & Linux (Shortcuts + Batch)
Press F2 on Windows, Return on Mac, F2 on Linux — plus how to rename many files at once and when to let AI name them from their content.
Invoice Organizer Software for Mac: Rename and File PDFs
Learn how invoice organizer software for Mac uses OCR, AI renaming, watch folders, and Finder tags to rename invoice PDFs, receipts, and tax files.
Try it yourself
Self-managed: 50 renames in the app. Managed trial starts in checkout.