MacTorn/wiki/Troubleshooting.md

Troubleshooting

This page covers common issues and their solutions.

Can't Open MacTorn (Gatekeeper)

Symptom: "MacTorn can't be opened because it is from an unidentified developer"

Cause: macOS Gatekeeper blocks unsigned applications.

Solution:

Method 1 - Right-Click Open:

1. Right-click (or Control-click) on MacTorn.app
2. Select "Open" from the menu
3. Click "Open" in the dialog

Method 2 - System Settings:

1. Try opening MacTorn (it will be blocked)
2. Go to System Settings > Privacy & Security
3. Scroll to find the message about MacTorn
4. Click "Open Anyway"
5. Enter your password and click "Open"

API Key Errors

"Invalid API Key"

Cause: The key you entered is incorrect or has been revoked.

Solution:

1. Go to https://www.torn.com/preferences.php#tab=api
2. Verify your key exists and matches what you entered
3. If in doubt, create a new key
4. Copy the key carefully (16 characters)
5. Re-enter in MacTorn Settings

"Insufficient Permissions"

Cause: Your API key doesn't have the required permissions.

Solution:

1. Create a new API key with "Full Access"
2. Or select these specific permissions:
   • basic, bars, cooldowns, travel, profile, events, messages, money, battlestats, attacks

"API Request Failed"

Cause: Network issue or Torn API is down.

Solution:

1. Check your internet connection
2. Try visiting https://www.torn.com to verify Torn is accessible
3. Wait and try again - Torn API occasionally has downtime
4. Click "Refresh" or wait for next automatic refresh

Menu Bar Icon Issues

Icon Not Appearing

Cause: MacTorn may not have launched properly.

Solution:

1. Check if MacTorn is running (Activity Monitor)
2. Quit and relaunch MacTorn
3. Check System Settings > Control Center > Menu Bar Only to ensure there's space

Wrong Icon Displayed

Cause: Normal behavior - icon changes based on status.

Reference:

• Bolt outline = Normal
• Bolt filled = Energy full
• Globe = Abroad
• Triangle = Error
• Airplane + timer = Traveling

Notifications Not Working

No Notifications Appear

Cause: macOS notification permissions.

Solution:

1. Open System Settings > Notifications
2. Find MacTorn in the list
3. Ensure "Allow Notifications" is ON
4. Set alert style to "Banners" or "Alerts"

Notification Sound Missing

Cause: Sound disabled in notification settings.

Solution:

1. System Settings > Notifications > MacTorn
2. Enable "Play sound for notifications"

Travel Alerts Not Working

Cause: Pre-arrival alerts may be disabled.

Solution:

1. Open MacTorn > Travel tab
2. Under "Pre-Arrival Alerts"
3. Enable the time intervals you want

Data Not Updating

Bars/Stats Stuck

Cause: Polling may have stopped or API error.

Solution:

1. Check the menu bar icon - triangle means error
2. Go to Settings and verify API key
3. Try changing refresh interval (triggers restart)
4. Quit and relaunch MacTorn

Watchlist Prices Not Loading

Cause: API v2 permissions or item ID issues.

Solution:

1. Ensure your API key has market access
2. Click the refresh button in Watchlist tab
3. Remove and re-add items

Performance Issues

High CPU Usage

Cause: Rare, possibly rendering loop.

Solution:

1. Quit and relaunch MacTorn
2. Try a longer refresh interval (60s or 2m)
3. If persists, file a bug report

App Feels Slow

Cause: Normal behavior during initial load.

Solution:

• MacTorn uses non-blocking data fetching
• UI should remain responsive
• First load may show empty data briefly

Window Issues

Window Won't Open

Cause: Window may be off-screen.

Solution:

1. Quit MacTorn
2. Run in Terminal: defaults delete com.bombel.MacTorn
3. Relaunch MacTorn

Window Too Small/Cut Off

Cause: Display scaling issues.

Solution:

1. Try different appearance mode in Settings
2. Quit and relaunch

Update Issues

"New Version Available" but Can't Update

Cause: Manual update required.

Solution:

1. Click "Download Update" in Settings
2. Download the new version from GitHub
3. Quit MacTorn
4. Replace old .app with new one
5. Relaunch (may need Gatekeeper bypass again)

Reporting Bugs

If your issue isn't listed here:

1. Check GitHub Issues - https://github.com/pawelorzech/MacTorn/issues
2. Create New Issue with:
   • macOS version
   • MacTorn version (found in Settings)
   • Steps to reproduce
   • Screenshots if applicable

---

See Also: FAQ for common questions