Troubleshooting Guide

Solutions to common issues and error messages.

Quick Diagnostics

Start here if something isn't working:

1. Restart Astronox - Fixes 70% of issues
2. Check API key - Settings → API Keys → Verify key is valid
3. Check internet - AI models require active connection
4. Check error message - Look in chat for specific error code
5. Check console - Help → Toggle Developer Tools (if tech-savvy)

Installation Issues

macOS: "App is damaged and can't be opened"

Error:

"Astronox.app" is damaged and can't be opened.
You should move it to the Trash.

Cause: Gatekeeper security blocking unsigned app

Solution:

# In Terminal:
xattr -cr /Applications/Astronox.app

# Or:
sudo spctl --master-disable
# Open app, then re-enable:
sudo spctl --master-enable

Alternative:

1. Right-click Astronox.app
2. Select "Open"
3. Click "Open" in dialog
4. Only needed once

Windows: "Windows protected your PC"

Error:

Windows Defender SmartScreen prevented an unrecognized app

Cause: App not signed with Microsoft certificate

Solution:

1. Click "More info"
2. Click "Run anyway"
3. Only needed on first launch

If that doesn't work:

1. Right-click installer → Properties
2. Check "Unblock" → Apply
3. Run installer again

Linux: Permission denied

Error:

bash: ./astronox: Permission denied

Solution:

chmod +x astronox
./astronox

"Failed to download update"

Error:

Update check failed
Network error

Causes:

• No internet connection
• Firewall blocking
• Proxy issues

Solutions:

Check connection:

# Test connectivity:
ping google.com

Disable firewall temporarily:

• See if update works
• If yes, add Astronox to firewall exceptions

Configure proxy (if behind corporate proxy):
Settings → Advanced → Proxy Settings

API Key Issues

"Invalid API key"

Error:

⚠️ API key rejected
The API key provided is invalid or has been revoked.

Solutions:

1. Verify key format:

Gemini: Should start with "AIza..."

2. Generate new key:

• Visit Google AI Studio
• Create new API key
• Replace in Settings → API Keys

3. Check for typos:

• No extra spaces
• Complete key copied
• Not truncated

4. Key might be revoked:

• Check Google Cloud Console
• Key may have been deleted
• Generate new one

"API key quota exceeded"

Error:

⚠️ Daily quota exceeded
You've reached the limit of 1,500 requests per day.
Resets at midnight PST.

Solutions:

Short term:

• Wait for quota reset (midnight PST)
• Switch to different model (separate quota)
• Use MintAI if available

Long term:

• Enable billing in Google Cloud
• Upgrade to paid tier
• Subscribe to Pro

See Rate Limits for details.

"Rate limit exceeded"

Error:

⚠️ Too many requests
Slow down - you're sending requests too fast.
Wait 60 seconds.

Solution:

• Wait 1 minute
• Limits reset automatically
• Batch multiple questions in one message

Prevention:

• Don't rapid-fire messages
• Combine related queries
• Use appropriate model (Pro has lower limits)

Connection Issues

"Network error"

Error:

❌ Failed to send message
Network error - check your connection

Diagnostics:

1. Test internet:

ping 8.8.8.8
# Should see replies

2. Test API access:

curl https://generativelanguage.googleapis.com
# Should get response (even error is fine)

3. Check firewall:

• Ensure Astronox can access internet
• Check corporate firewall
• Try different network

4. Check proxy:

• If behind proxy, configure in Settings
• May need proxy credentials

"Request timeout"

Error:

⚠️ Request timed out after 60 seconds
The AI model didn't respond in time.

Causes:

• Model overloaded
• Very complex request
• Network congestion
• API outage

Solutions:

• Retry request
• Simplify prompt
• Switch model
• Check Google Status

"SSL certificate error"

Error:

SSL verification failed

Causes:

• Corporate proxy
• Antivirus intercepting HTTPS
• System time incorrect

Solutions:

1. Check system time:

• Must be accurate for SSL
• Set to automatic

2. Check antivirus:

• Disable SSL scanning temporarily
• Add exception for Astronox

3. Corporate proxy:

• Install proxy certificates
• Configure proxy settings

UI Issues

Chat not scrolling

Symptom: New messages appear but don't auto-scroll

Solution:

1. Scroll manually to bottom
2. Restart app
3. Clear conversation (if very long)

Prevention:

• Start fresh chats periodically
• Don't let conversations exceed 100 messages

Messages appearing twice

Symptom: Same message shows up multiple times

Cause: UI rendering glitch

Solution:

1. Refresh conversation:
   • Click away and back
   • Or restart app
2. If persists, clear cache:
   • Settings → Advanced → Clear Cache

Settings not saving

Symptom: Changes revert after restart

Causes:

• Permission issues
• Corrupted settings file
• App data directory not writable

Solutions:

macOS:

# Check permissions:
ls -la ~/Library/Application\ Support/dev.mintai.astronox/

# Fix permissions:
chmod -R u+w ~/Library/Application\ Support/dev.mintai.astronox/

Windows:

# Check folder exists:
dir %APPDATA%\dev.mintai.astronox

# Reset permissions:
# Right-click folder → Properties → Security → Edit
# Give your user Full Control

Linux:

# Check permissions:
ls -la ~/.config/dev.mintai.astronox/

# Fix:
chmod -R u+w ~/.config/dev.mintai.astronox/

Attachments not showing

Symptom: Uploaded images don't appear

Causes:

• File too large (>5MB per file)
• Unsupported format
• Conversation attachment limit (8MB total)

Solutions:

1. Check file size (must be <5MB)
2. Check format (JPG, PNG, GIF, WebP only)
3. Clear old attachments
4. Start new conversation

Dark theme too dark / light theme too light

Solution:
Settings → Appearance → Adjust brightness slider

Or use system theme:
Settings → Appearance → Follow System

Performance Issues

Slow responses

Causes:

• Model selected (Pro is slower)
• Complex request
• API rate limiting
• Network latency

Solutions:

• Switch to Flash or Flash Lite
• Simplify request
• Check internet speed
• Wait a moment and retry

App freezing

Symptom: UI becomes unresponsive

Causes:

• Very long conversation
• Memory leak
• Background process stuck

Solutions:

Immediate:

1. Force quit (Cmd/Ctrl + Q)
2. Restart app

Long term:

1. Start fresh conversations
2. Clear old chats
3. Update to latest version

High memory usage

Symptom: App using >1GB RAM

Causes:

• Long conversations
• Many attachments
• Memory leak (rare)

Solutions:

1. Restart app (clears memory)
2. Delete old conversations
3. Remove attachments
4. Update app (fixes leaks)

Tool Execution Issues

"Tool confirmation required but no response"

Symptom: Chat says "Waiting for confirmation..." but no button appears

Cause: UI state desync

Solution:

1. Refresh UI (click away and back)
2. Respond with "yes" or "no" in chat
3. Restart app if persists

"Permission denied" errors

Error:

❌ Permission denied
Cannot access /path/to/file

Causes:

• File owned by different user
• Protected system file
• macOS/Windows security restrictions

Solutions:

Check file ownership:

ls -la /path/to/file

Grant permissions:

chmod +r /path/to/file  # Read
chmod +w /path/to/file  # Write

macOS specific:
System Preferences → Security & Privacy → Privacy

• Grant Full Disk Access to Astronox

Windows specific:
Right-click file → Properties → Security

• Add your user with appropriate permissions

"File not found" when file exists

Causes:

• Path typo (check spaces, case)
• Relative vs absolute path
• File in different directory
• Permission issue hiding file

Solutions:

Use absolute paths:

❌ "data/file.txt"
✅ "/Users/you/Documents/data/file.txt"

Check file exists:

ls -la /full/path/to/file.txt

Let AI find it:

"Find file.txt in Documents folder"

Shell commands not working

Error:

Command failed with exit code 127

Cause: Command not found or not in PATH

Solutions:

Use full path:

❌ python script.py
✅ /usr/bin/python3 script.py

Check command exists:

which python
# Should show path like /usr/bin/python

Install missing command:

# macOS:
brew install <command>

# Linux:
sudo apt install <command>

Model-Specific Issues

Gemini Pro is slow

This is normal:

• Pro prioritizes quality over speed
• Takes 2-3x longer than Flash
• Worth it for complex tasks

If too slow:

• Switch to Flash for most tasks
• Reserve Pro for complex work
• Or use Devstral 2 (faster)

Flash Lite gives poor results

This is expected:

• Lite is optimized for speed, not quality
• Good for simple tasks only
• Limited reasoning ability

Solution:

• Use Flash for general tasks
• Use Pro for complex work
• See Model Selection

"Model not available"

Error:

The selected model is currently unavailable

Causes:

• API outage
• Model deprecated
• Region restrictions

Solutions:

1. Switch to different model
2. Check Google Status
3. Wait and retry
4. Use MintAI as backup

Memory System Issues

Memory not being recalled

Symptom: AI forgets things you told it to remember

Causes:

• Memory system disabled
• Fact not saved correctly
• Category mismatch
• Too many memories (AI skips some)

Solutions:

Check memory is enabled:
Settings → Memory → Enabled ✓

Verify memory was saved:
Settings → Memory → View All Facts

• Look for your fact
• If missing, re-save it

Be explicit:

❌ "Remember my name"
✅ "Remember: My name is Alex"

Use categories:

"Remember in category 'preferences': I prefer Python"

Too many memory facts

Symptom: Memory tab has hundreds of entries

Effect:

• AI gets overwhelmed
• Slower processing
• May skip facts

Solution:

1. Settings → Memory
2. Delete outdated facts
3. Keep only relevant info
4. Use categories to organize

Best practice:

• Quality over quantity
• <50 facts ideal
• Review and prune monthly

Automation Issues

Saved script not appearing

Symptom: Saved automation doesn't show in list

Causes:

• Save failed silently
• File permission issue
• UI not refreshed

Solutions:

1. Refresh automations list (click away and back)

2. Check file was created:

   # macOS:
   ls ~/Library/Application\ Support/dev.mintai.astronox/automations/
   
   # Windows:
   dir %APPDATA%\dev.mintai.astronox\automations\
   
   # Linux:
   ls ~/.config/dev.mintai.astronox/automations/
   

3. Re-save automation

4. Check disk space

Automation runs but fails

Symptom: Script executes but doesn't work as expected

Causes:

• Paths changed
• Dependencies missing
• Permissions changed
• Environment variables not set

Solutions:

1. Review script content
2. Update paths to absolute
3. Test manually first
4. Check error messages

Update Issues

"Update available" notification won't go away

Symptom: Dismissing update notice doesn't persist

Causes:

• Settings not saving
• Update check running repeatedly

Solutions:

1. Install the update (recommended)
2. Settings → Updates → Disable auto-check
3. Restart app

Update fails to install

Error:

Update installation failed
Error code: UPDATE_001

Solutions:

1. Manual update:

• Download latest from [official site]
• Install manually
• Overwrite existing installation

2. Check permissions:

• May need admin/sudo
• Close app completely first

3. Clean install:

• Backup conversations
• Uninstall Astronox
• Fresh install
• Restore conversations

Data & Storage Issues

Conversations lost after update

Cause: Data directory moved or permissions changed

Recovery:

macOS:

# Check backup location:
ls ~/Library/Application\ Support/dev.mintai.astronox/chat_sessions/

Windows:

dir %APPDATA%\dev.mintai.astronox\chat_sessions\

If found:

• Conversations should load automatically
• If not, check file permissions

If lost:

• No built-in recovery (yet)
• Future: Cloud backup planned

"Storage quota exceeded"

Error:

⚠️ Cannot save attachments
Conversation storage limit reached (8MB)

Solutions:

1. Remove old attachments:
   • Click attachment → Delete
2. Start new conversation
3. Compress images before uploading

Prevention:

• Use file paths instead of uploading
• Start fresh chats for new topics
• Delete old conversations

Platform-Specific Issues

macOS: Brightness control not working

Known issue - M4 chips only

Symptoms:

• Brightness tool doesn't change display brightness
• No error message

Cause: Apple Silicon M4 compatibility issue

Status: Under investigation

Workaround:

• Use System Settings → Displays
• Or use physical brightness keys (F1/F2)

See M4 Brightness Analysis

Windows: "Operation not permitted"

Error:

❌ Operation not permitted
Administrator rights required

Solution:

1. Right-click Astronox
2. "Run as administrator"
3. Retry operation

Note: Only needed for system-level operations

Linux: AppImage won't launch

Error:

Cannot execute binary file

Solutions:

1. Make executable:

chmod +x Astronox.AppImage

2. Install FUSE:

# Ubuntu/Debian:
sudo apt install fuse libfuse2

# Fedora:
sudo dnf install fuse

3. Extract and run:

./Astronox.AppImage --appimage-extract
./squashfs-root/AppRun

Getting More Help

Enable Debug Mode

Access detailed logs:

1. Help → Toggle Developer Tools
2. Click "Console" tab
3. Look for error messages (red text)
4. Copy error details

Collect Diagnostic Info

Before reporting issue:

1. App version:
   • Settings → About → Version
2. OS version:
   • macOS: System Settings → General → About
   • Windows: Settings → System → About
   • Linux: uname -a
3. Error message (exact text)
4. Steps to reproduce
5. Screenshots (if UI issue)

Report a Bug

How to report:

1. Open issue on GitHub (if available)
2. Or email support (check official site)
3. Include:
   • Diagnostic info (above)
   • What you expected
   • What actually happened
   • Screenshots
   • Logs (if available)

Community Support

Resources:

• GitHub Discussions (if available)
• Official Discord (check website)
• User forums

Before asking:

1. Search existing issues
2. Check this troubleshooting guide
3. Try basic fixes (restart, etc.)

Emergency Procedures

Complete Reset

⚠️ Warning: Deletes all conversations, settings, memory

When to use:

• App completely broken
• Corrupted data
• Last resort only

Procedure:

macOS:

rm -rf ~/Library/Application\ Support/dev.mintai.astronox/

Windows:

rmdir /s %APPDATA%\dev.mintai.astronox\

Linux:

rm -rf ~/.config/dev.mintai.astronox/

Then restart app (fresh state).

Backup Before Reset

Save your data first:

macOS:

cp -r ~/Library/Application\ Support/dev.mintai.astronox/ ~/Desktop/astronox-backup/

Windows:

xcopy %APPDATA%\dev.mintai.astronox\ %USERPROFILE%\Desktop\astronox-backup\ /E /I

Linux:

cp -r ~/.config/dev.mintai.astronox/ ~/Desktop/astronox-backup/

Still Not Working?

If nothing in this guide helped:

1. Check GitHub Issues for known bugs
2. Review Limitations - might be expected
3. Ask in Community Forums
4. Contact support with diagnostic info

Most issues are fixable! Don't give up - there's usually a solution.

Next: Frequently Asked Questions for quick answers.