Troubleshooting

Most issues fall into one of four buckets: macOS permissions, AI provider configuration, credits/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).

Credits, trial & license#

Trial exhausted — the free trial includes 50 renames over 7 days. When it ends, pick a plan in Settings → Usage or on the pricing page: Managed credits from $5/month, or the $38 one-time Self-Managed license with your own key or a local model.

Out of credits (Managed) — your monthly credits ran out. Settings → Usage shows your balance and renewal date; you can upgrade tiers anytime, and unused credits 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.