Skip to main content

​
Common issues

This guide covers the most frequently encountered issues and their solutions.

​
Permissions problems

​
Full Disk Access not granted

Solution:jo requires Full Disk Access to index your files, emails, and browser history.
1

Open System Settings

Go to Apple menu > System Settings > Privacy & Security > Full Disk Access
2

Add jo to the list

Click the + button and navigate to Applications > jo. Select jo and click Open.
3

Enable the toggle

Ensure the toggle next to jo is turned ON.
4

Restart jo

Quit jo completely (Cmd+Q) and relaunch it.
macOS may require you to enter your admin password to grant Full Disk Access.

​
Email access issues

Common causes:
  1. App-specific password required: Gmail, Outlook, and iCloud require app-specific passwords instead of your regular password
  2. IMAP not enabled: Some email providers disable IMAP by default
  3. Firewall blocking connection: Corporate or home firewalls may block IMAP ports
Solutions:
1

Generate app-specific password

For Gmail:
  • Go to Google Account > Security > 2-Step Verification > App passwords
  • Generate a password for “Mail” and “Mac”
  • Use this password in jo instead of your regular password
For Outlook/Microsoft:
  • Go to account.microsoft.com > Security > Advanced security options
  • Under “App passwords”, create a new password
  • Use this in jo’s email settings
For iCloud:
  • Go to appleid.apple.com > Sign-In and Security > App-Specific Passwords
  • Generate a new password labeled “jo”
  • Use this in jo’s configuration
2

Enable IMAP

Gmail: Settings > Forwarding and POP/IMAP > Enable IMAPOutlook: Settings > Mail > Sync email > Enable IMAPiCloud: IMAP is enabled by default
3

Check firewall settings

Ensure ports 993 (IMAP SSL) and 587 (SMTP) are not blocked in your firewall settings.
4

Test connection

In jo, go to Settings > Data Sources > Email > Test Connection to verify.

​
Browser history access

Solution:
1

Grant Full Disk Access

Browser history requires Full Disk Access (see above).
2

Check browser compatibility

jo supports:
  • Safari (fully supported)
  • Chrome (fully supported)
  • Firefox (fully supported)
  • Brave (fully supported)
  • Arc (fully supported)
3

Verify browser is closed

Some browsers lock their history database while running. Close your browser and let jo re-index.
4

Re-enable browser history indexing

Go to Settings > Data Sources > Browser History and toggle your browser on/off.

​
Indexing issues

​
Indexing stuck or frozen

Diagnosis:Check Settings > Data Sources > Indexing Status to see which source is stuck.Solutions:
1

Identify problematic files

Look for patterns:
  • Very large files (>1GB)
  • Corrupted files
  • Network drives that disconnected
  • Files with special characters or encoding issues
2

Exclude problematic paths

In Settings > Data Sources > [Source] > Exclusions, add paths causing issues.
3

Restart indexing

In Settings > Data Sources > [Source] > Actions > Restart Indexing
4

Check available disk space

Ensure you have at least 5GB free space. Jo needs temporary space during indexing.
If indexing remains stuck after these steps, see “Reset index” in the Data Management section.

​
Indexing too slow

Common causes:
  • Indexing large volumes of data (100,000+ files)
  • Low memory availability (less than 8GB free)
  • Files on slow external drives
  • Background system tasks competing for resources
Solutions:
1

Prioritize sources

In Settings > Data Sources, disable less important sources temporarily. Index critical folders first.
2

Schedule indexing

Settings > Indexing > Schedule: Set indexing to occur during off-hours or when Mac is plugged in.
3

Close resource-heavy apps

Quit video editing, gaming, or other memory-intensive applications while indexing.
4

Use internal storage

If possible, copy frequently-accessed files to your internal SSD for faster indexing.

​
Missing recent files

Check:
  1. File modification time (jo indexes based on modification, not creation date)
  2. File location is included in indexed paths
  3. File type is not excluded (Settings > Data Sources > File Types)
Force re-index:
1

Navigate to source settings

Settings > Data Sources > Files > [Specific folder]
2

Click 'Re-index this folder'

This forces jo to scan for changes immediately.
3

Wait for completion

Small folders re-index in seconds; large folders may take minutes.

​
Cloud model connection issues

​
API key errors

Solution:
1

Verify API key

Log into your provider’s dashboard:
  • OpenAI: platform.openai.com/api-keys
  • Anthropic (Claude): console.anthropic.com/settings/keys
  • Google (Gemini): makersuite.google.com/app/apikey
Confirm your key is active and not expired.
2

Re-enter key in jo

Settings > Cloud Models > [Provider] > API KeyCopy-paste the key carefully (no extra spaces).
3

Check billing status

Ensure your provider account has payment information and available credits.
4

Test connection

Click “Test Connection” to verify before using in queries.

​
Rate limiting

Cause: API providers limit requests per minute/hour.Solution:
1

Wait before retrying

Rate limits typically reset within 1-5 minutes. Jo will automatically retry.
2

Reduce query frequency

If hitting limits frequently, space out queries or batch your questions.
3

Upgrade provider tier

Consider upgrading your API plan for higher rate limits:
  • OpenAI: platform.openai.com/account/billing
  • Anthropic: console.anthropic.com/settings/plans

​
Slow cloud responses

Diagnosis:
1

Check network speed

Run a speed test. You need at least 5 Mbps upload for smooth streaming.
2

Verify API region

Settings > Cloud Models > [Provider] > RegionSelect the region closest to you.
3

Reduce context size

Large context from your index increases processing time. In Settings > Cloud Models > Context, reduce “Max context documents” from 20 to 10.

​
General troubleshooting

​
jo won’t launch

Solutions:
1

Check system requirements

Verify you have:
  • Mac with M-series chip (M1, M2, M3, or M4)
  • macOS 12.0 or later
  • 16GB RAM minimum
2

Restart your Mac

Sometimes macOS services need to be refreshed.
3

Re-download jo

Download the latest version from askjo.ai and replace the existing app.
4

Check Console.app for errors

Open Console.app, search for “jo”, and look for crash reports or error messages. These can help identify specific issues.
If jo continues to crash, see “Complete uninstall” in Data Management to do a clean reinstall.

​
High CPU usage

Normal scenarios:
  • Initial indexing (CPU usage 40-80%)
  • Background re-indexing after system wake
  • Processing large query results
If sustained when idle:
1

Check indexing status

Settings > Data Sources > Indexing StatusEnsure no tasks are stuck in a loop.
2

Restart jo

Quit completely (Cmd+Q) and relaunch.
3

Reduce monitoring frequency

Settings > Data Sources > Advanced > File MonitoringChange from “Real-time” to “Every 5 minutes” to reduce background activity.

​
Search results not relevant

Causes:
  • Index out of sync with file system
  • Query too vague
  • Ranking algorithm not tuned
Solutions:
1

Re-index affected sources

Settings > Data Sources > [Source] > Re-index
2

Use more specific queries

Instead of: “project files” Try: “Acme Corp proposal PDF from last week”
3

Adjust relevance settings

Settings > Search > RelevanceIncrease weight for recent files or specific file types.
4

Use filters

Specify source: “in my email”, “in Documents folder” Add dates: “since January”, “last month”

​
Getting more help

​
Check system status

Settings > Advanced > System Diagnostics provides detailed info:
  • Index health
  • Memory and disk usage
  • Recent errors
  • Performance metrics
Export this report when contacting support.

​
Enable debug logging

1

Enable debug mode

Settings > Advanced > Debug Logging > Enable
2

Reproduce the issue

Perform the action that’s causing problems.
3

Export logs

Settings > Advanced > Debug Logging > Export LogsSave the file and attach when reporting issues.
4

Disable debug mode

Debug logging increases disk usage. Turn it off after capturing logs.

​
Contact support

If issues persist:
  • Email: [email protected]
  • Include: System Diagnostics report, debug logs (if enabled), and description of the issue
  • Expected response: Within 24-48 hours

​
Next steps

Performance

Optimize jo for speed and efficiency

Data management

Manage storage and backups

Build docs developers (and LLMs) love

Get started for freeTalk to us