Common Issues

Common Issues

Solutions to the most frequently encountered problems.

Installation Issues

”ClipboardRecast.app” can’t be opened / app is damaged

Cause: macOS Gatekeeper quarantines apps downloaded from the internet that aren’t signed with an Apple Developer certificate. This is not an actual problem with the app — it’s a security gate Apple applies to all unsigned software.

The fix — run this in Terminal:

xattr -cr /Applications/ClipboardRecast.app

This removes the quarantine attribute macOS attached to the file when you downloaded it. After running it, double-click the app normally and it will open without any warning.

Why right-click → Open may not work:

On macOS Ventura (13) and Sonoma (14), Apple tightened this restriction. For fully unsigned apps, the “Open Anyway” option may not appear when you right-click, and the Privacy & Security panel may not show it either. The xattr Terminal command is the reliable workaround in all cases.

Step by step:

1. Open Terminal (press Cmd+Space, type “Terminal”, press Enter)
2. Paste this command and press Enter:

   xattr -cr /Applications/ClipboardRecast.app

3. If you installed the app somewhere other than /Applications, adjust the path:

   xattr -cr ~/Downloads/ClipboardRecast.app

4. Double-click Clipboard Recast — it will now open normally

You only need to do this once. The app will launch normally from then on.

App doesn’t appear in menu bar

Solutions:

1. Check Activity Monitor - search for “ClipboardRecast” to see if it’s running
2. Look at the right side of your menu bar (icon may be hidden)
3. Try launching from Applications folder again
4. Check Console.app for error messages
5. Reinstall the app from the DMG

Runtime Issues

Global Hotkey Not Working

Problem: Cmd+Shift+A doesn’t trigger transformations

Cause: Missing Accessibility permissions

Solution:

1. Open System Settings → Privacy & Security → Accessibility
2. Click the lock icon to make changes
3. Click + button and add ClipboardRecast
4. Ensure checkbox is enabled
5. Quit and relaunch the app

Verification:

• Copy some text
• Press Cmd+Shift+A
• Dialog should appear

Transformations Failing

Error: “No AI Provider Configured”

• Click menu bar → Settings
• Select AI provider
• Enter API key
• Click Save

Error: “Invalid API key”

• Verify key is correct (no extra spaces)
• Check if key has necessary permissions
• Ensure billing is set up with provider

Error: “Rate limit exceeded”

• Wait a few minutes
• Check provider’s rate limits
• Consider upgrading plan

Error: “Invalid response format”

• Provider may be down - check status page
• Try different model in Settings
• Verify API key has access to selected model

Error: “Network error”

• Check internet connection
• Verify firewall isn’t blocking app
• Try different network

Error: “Project ID required” (Vertex AI)

• Enter Google Cloud Project ID in Settings
• Ensure Vertex AI API is enabled

Clipboard Not Being Monitored

Problem: Copying text doesn’t trigger auto-workflows

Solutions:

1. Check “Auto-process clipboard changes” is enabled in Workflows
2. Verify workflows have “Auto-trigger” checked
3. Restart the app
4. Check Console.app for errors

Workflows Not Matching Content

Problem: Workflow should match but doesn’t trigger

Debug Steps:

1. Open Workflows window
2. Verify workflow is Enabled
3. Check trigger type matches content
4. For Text triggers, verify keywords match
5. Test manually with Cmd+Shift+A

Screenshots Not Detected

Problem: Taking screenshots but they don’t appear in history

Solutions:

1. Use Cmd+Shift+4 (saves to Desktop) not Cmd+Shift+Control+4
2. Wait 2-3 seconds for detection
3. Check screenshots are saving to Desktop
4. Verify filename matches pattern: “Screenshot YYYY-MM-DD…”

Screenshot Analysis Fails

Error: “Model doesn’t support images”

• Provider doesn’t support vision (Cerebras, Together AI, z.ai)
• Or using wrong model (e.g., gemini-pro instead of gemini-pro-vision)
• Change to vision-capable provider or model

Solutions:

• Switch to Claude, OpenAI, or Gemini
• For Gemini: Change model to gemini-pro-vision
• For OpenAI: Change model to gpt-4-vision-preview

Performance Issues

App Using Too Much CPU

Solutions:

• Check if stuck in processing loop
• Restart the app
• Disable auto-processing temporarily
• Check Console.app for errors

Slow Response Times

Solutions:

• Try different AI provider
• Use faster model (e.g., Claude Haiku, GPT-4o Mini)
• Check internet connection speed
• Verify provider isn’t experiencing issues

Memory Issues

Solutions:

• Quit and relaunch app
• Clear clipboard history (if available)
• Check for memory leaks in Console.app

macOS-Specific Issues

App Doesn’t Start After macOS Update

Solutions:

1. Re-grant Accessibility permissions
2. Reinstall the app
3. Check Console.app for new permission requirements

Conflicts with Other Clipboard Managers

Problem: Using multiple clipboard managers causes conflicts

Solutions:

• Disable other clipboard managers
• Or disable Clipboard Recast’s monitoring
• Use only one clipboard manager at a time

Getting More Help

If your issue isn’t listed here:

1. Check Console.app: Search for “ClipboardRecast” to see error messages
2. Enable Debug Logs: See Debug Workflows
3. Check Provider Status: Visit your AI provider’s status page
4. Contact Support: Reach out through the app’s support channels

Quick Diagnostic Checklist

Run through this checklist to diagnose issues:

• App appears in Activity Monitor?
• Menu bar icon visible?
• Accessibility permissions granted?
• AI provider and API key configured?
• Internet connection working?
• Provider service status online?
• Workflows enabled?
• Content matches workflow triggers?

Next Steps

• Debug Workflows: Advanced debugging techniques
• Privacy & Security: Security-related questions
• Configuration: Review your settings