HarborDB

Common Issues & Troubleshooting

Support
•Last updated: February 16, 2026

Welcome to the HarborDB troubleshooting guide. This comprehensive resource helps you quickly identify and resolve the most common issues encountered while working with HarborDB and PostgreSQL. Whether you're experiencing connection problems, slow performance, or interface issues, you'll find step-by-step solutions here.

How to Use This Guide

  1. Identify your issue from the categories below
  2. Follow the troubleshooting steps in order
  3. Try the solutions until the issue is resolved
  4. If still unresolved, use the "Contacting Support" section

Quick Reference: Common Issues

| Issue | Likely Cause | Quick Solution | | --------------------------- | ------------------------------------- | ----------------------------------------- | | Can't connect to PostgreSQL | Server not running, firewall blocking | Start PostgreSQL, check firewall settings | | Slow query performance | Missing indexes, large datasets | Add indexes, use LIMIT, optimize queries | | High memory usage | Too many open tabs, large result sets | Close unused tabs, enable streaming mode | | Export fails | Permission issues, disk full | Check file permissions, free disk space | | UI feels sluggish | System resource constraints | Close other apps, restart HarborDB |

Connection Issues

"Cannot connect to PostgreSQL server"

Symptoms:

  • Connection timeout errors
  • "Connection refused" messages
  • Infinite loading when testing connection

Step-by-Step Troubleshooting:

  1. Check PostgreSQL Server Status:

    # In Terminal, check if PostgreSQL is running
pg_isready -h localhost -p 5432
    • If not running: brew services start postgresql (Homebrew) or start via System Preferences

  2. Verify Connection Details:

    • Hostname: localhost for local, correct IP/hostname for remote
    • Port: Default is 5432, confirm your PostgreSQL port
    • Database name: Must exist before connecting
    • Username/password: Case-sensitive, check credentials

  3. Check Firewall Settings:

    • System Preferences → Security & Privacy → Firewall
    • Ensure PostgreSQL port (5432) is allowed
    • Try temporarily disabling firewall for testing

  4. Test Network Connectivity:

    # For remote servers
ping your-server-address
telnet your-server-address 5432

Common Solutions:

  • ✅ Start PostgreSQL service
  • ✅ Correct hostname/IP address
  • ✅ Open firewall port 5432
  • ✅ Use correct credentials

"Password authentication failed"

Causes:

  • Incorrect username or password
  • PostgreSQL authentication method mismatch
  • User lacks database permissions

Solutions:

  1. Reset PostgreSQL Password:

    -- Connect as superuser (via command line)
ALTER USER username WITH PASSWORD 'new_password';

  2. Check Authentication Method:

    • View pg_hba.conf file
    • Common methods: md5, scram-sha-256, trust
    • Update method if needed, restart PostgreSQL

  3. Verify User Permissions:

    -- List users and permissions
\du

-- List databases and access
\l

SSL/TLS Connection Errors

When connecting to remote servers:

  1. Check SSL Requirements:

    • Server may require specific SSL mode
    • May need certificate import

  2. Try Different SSL Modes in HarborDB:

    • Start with prefer
    • Then try require
    • Finally verify-full (requires certificate)

  3. Import Certificates if using verify-full:

    • Obtain certificate from server administrator
    • Import to macOS Keychain Access
    • Grant HarborDB access to certificate

Performance Issues

Slow Query Execution

Diagnosis Steps:

  1. Use EXPLAIN to Analyze:

    • Click "Explain" (⚡) button in HarborDB
    • Look for "Seq Scan" (full table scan) - often slow
    • Look for "Index Scan" - usually faster

  2. Check for Missing Indexes:

    -- Find frequently filtered columns without indexes
SELECT schemaname, tablename, attname
FROM pg_stats
WHERE schemaname NOT LIKE 'pg_%'
  AND n_distinct > 100
  AND attname NOT IN (
    SELECT column_name
    FROM information_schema.columns
    WHERE table_schema = schemaname
      AND table_name = tablename
  );

  3. Add Appropriate Indexes:

    -- Single column index
CREATE INDEX idx_table_column ON table_name(column_name);

-- Multi-column index for common query patterns
CREATE INDEX idx_table_col1_col2 ON table_name(col1, col2);

Quick Performance Fixes:

  • Add LIMIT clause to exploratory queries
  • Select only needed columns (not SELECT *)
  • Use WHERE clauses with indexed columns
  • Avoid functions in WHERE clauses that prevent index use

High Memory Usage

Symptoms:

  • HarborDB uses excessive RAM (check Activity Monitor)
  • System becomes sluggish
  • "Out of memory" errors

Solutions:

  1. Reduce Query Cache Size:

    • Preferences → Performance → Query Cache
    • Reduce from default 256MB to 128MB if memory constrained

  2. Enable Streaming Mode:

    • Preferences → Performance → Streaming Results
    • Enable for results > 10,000 rows
    • Reduces memory usage for large datasets

  3. Manage Open Tabs:

    • Close unused query tabs
    • HarborDB keeps result sets in memory per tab
    • Regular work: 5-10 tabs maximum

  4. Restart HarborDB:

    • Quit and restart daily during heavy use
    • Clears accumulated memory usage

Application Feels Sluggish

Quick Fixes:

  1. Close Other Applications:

    • Especially resource-intensive apps (Chrome with many tabs, Docker, etc.)
    • Check Activity Monitor for memory pressure

  2. Reduce UI Animations:

    • Preferences → Appearance → Disable animations
    • Smoother experience on older hardware

  3. Simplify Interface:

    • Collapse sidebar sections not in use
    • Use simpler color theme
    • Disable syntax highlighting for very large queries

Export and File Issues

Export Fails or Creates Empty Files

Common Causes and Solutions:

  1. Permission Issues:

    # Check folder permissions
ls -la ~/Desktop/

# Try different save location
# Use Documents folder instead of Desktop

  2. Disk Space Problems:

    # Check available disk space
df -h

# Need at least 2x export size free

  3. File Format Issues:

    • CSV: Try different delimiter (comma, semicolon, tab)
    • CSV: Add text qualifiers (quotes around fields)
    • JSON: Try both "Pretty" and "Compact" formats

  4. Large Export Optimization:

    • Export in smaller chunks
    • Use CSV instead of JSON for large datasets
    • Enable compression in export settings

"File Not Found" or Missing Exports

  1. Check Default Save Location:

    • Preferences → Export → Default Save Location
    • Change to frequently accessed folder

  2. Search for Files:

    # Search for recent CSV/JSON files
find ~ -name "*.csv" -mtime -1
find ~ -name "*.json" -mtime -1

  3. Check Trash:

    • Exports might have been accidentally deleted
    • Restore from Trash if found

Interface and Display Issues

Theme Not Applying Correctly

macOS Dark/Light Mode Issues:

  1. Check System Settings:

    • System Settings → Appearance
    • Ensure "Auto" or desired theme selected

  2. Restart HarborDB:

    • Quit completely (⌘ + Q)
    • Reopen to apply system theme

  3. Force Theme in HarborDB:

    • Preferences → Appearance → Theme
    • Choose "Light", "Dark", or "System"

Missing Features or Menus

  1. Update HarborDB:

    • Check for updates (HarborDB → Check for Updates)
    • App Store → Updates tab

  2. Reset Interface Layout:

    • Window → Reset Layout
    • Restores default panel arrangement

  3. Check Feature Availability:

    • Some features require specific PostgreSQL versions
    • Verify compatibility in feature documentation

Text Display Problems

Font Size/Readability Issues:

  1. Adjust Editor Font Size:

    • Preferences → Editor → Font Size
    • Increase for better readability

  2. Use macOS Zoom:

    • System Settings → Accessibility → Zoom
    • Enable for temporary magnification

  3. High Contrast Mode:

    • System Settings → Accessibility → Display
    • Increase contrast for better visibility

macOS-Specific Issues

"App is Damaged" Error

When opening HarborDB:

# Remove quarantine attribute
sudo xattr -cr /Applications/HarborDB.app

# Reopen HarborDB
open /Applications/HarborDB.app

Gatekeeper Warnings

For direct downloads (not App Store):

  1. System Settings → Privacy & Security
  2. Scroll to "Security" section
  3. Click "Open Anyway" next to HarborDB warning
  4. Confirm opening

Touch ID/Keychain Access Issues

"HarborDB wants to use your password" errors:

  1. Reset Keychain Permissions:

    • Open Keychain Access app
    • Search for "HarborDB"
    • Delete existing entries
    • Re-add connection in HarborDB

  2. Repair Keychain:

    • Keychain Access → File → Keychain First Aid
    • Run repair on "Login" keychain

Compatibility with macOS Versions

Minimum: macOS 12.0 (Monterey) Recommended: macOS 13.0 (Ventura) or later

Check Compatibility:

# Check macOS version
sw_vers

# Check architecture (Apple Silicon vs Intel)
uname -m

Database-Specific Issues

"Relation does not exist"

When querying tables:

  1. Check Schema:

    -- List all tables in current schema
\dt

-- List tables in all schemas
SELECT schemaname, tablename
FROM pg_tables
WHERE tablename LIKE '%your_table%';

  2. Use Qualified Names:

    -- Instead of: SELECT * FROM users;
-- Use schema qualification:
SELECT * FROM public.users;
SELECT * FROM auth.users;

  3. Set Default Schema:

    • Edit connection in HarborDB
    • Set "Default Schema" to commonly used schema

Permission Errors on Database Objects

Permission denied for relation

  1. Check Your Permissions:

    -- Connect as superuser or table owner
SELECT grantee, privilege_type
FROM information_schema.role_table_grants
WHERE table_name = 'your_table';

  2. Request Permissions:

    -- Example: Grant SELECT permission
GRANT SELECT ON table_name TO your_username;

Large Dataset Handling

"Out of memory" or extremely slow:

  1. Use Server-Side Pagination:

    -- Instead of: SELECT * FROM huge_table;
-- Use:
SELECT * FROM huge_table LIMIT 1000 OFFSET 0;
-- Then increment OFFSET for next pages

  2. Enable Streaming in HarborDB:

    • Preferences → Performance → Streaming Mode
    • Set threshold (e.g., 10,000 rows)

  3. Use Materialized Views for frequent complex queries

Network and Remote Connection Issues

Slow Remote Connections

Optimization Tips:

  1. Enable Compression:

    • Connection settings → Advanced → Compression
    • Reduces data transfer size

  2. Use SSH Tunneling:

    • More secure than direct connection
    • Can improve performance on restricted networks

  3. Schedule Heavy Queries:

    • Run during off-peak hours
    • Use HarborDB's query scheduler feature

Intermittent Connection Drops

  1. Increase Timeout Settings:

    • Connection settings → Timeout
    • Increase from 30 to 60 seconds

  2. Enable Keep-Alive:

    • Connection settings → Keep-Alive
    • Maintains idle connections

  3. Check Network Stability:

    # Test network stability
ping -c 100 your-server-address
# Look for packet loss

Before Contacting Support

Information to Collect

If issues persist after troubleshooting, gather this information:

  1. System Information:

    • macOS version (Apple menu → About This Mac)
    • HarborDB version (HarborDB → About HarborDB)
    • PostgreSQL version (SELECT version();)

  2. Error Details:

    • Exact error message (screenshot if possible)
    • Steps to reproduce the issue
    • When the issue started

  3. Configuration Details:

    • Connection settings (without passwords)
    • Query causing issues (if applicable)
    • Export settings (if export-related)

Diagnostic Tools in HarborDB

  1. Generate Diagnostic Report:

    • Help → Create Diagnostic Report
    • Includes logs, configuration, system info

  2. View Application Logs:

    • Help → Show Logs
    • Filter for error and warning messages

  3. Console.app for System Logs:

    • Open Console.app
    • Search for "HarborDB"
    • Look for crash reports

Quick Self-Check

Before contacting support, verify:

  • [ ] macOS is up to date
  • [ ] HarborDB is latest version
  • [ ] PostgreSQL server is running
  • [ ] Network connection is stable
  • [ ] Sufficient disk space available
  • [ ] User has necessary permissions

Contacting Support

If you've tried all troubleshooting steps and the issue persists:

  1. Email Support: support@harbordb.com

  2. Include in your email:

    • Diagnostic report (from Help menu)
    • Screenshots of error messages
    • Steps to reproduce the issue
    • What troubleshooting steps you've tried

  3. Expected Response Time:

    • Initial response: Within 24-48 hours
    • Business hours: Monday-Friday, 9AM-5PM EST
    • Emergency issues: Mark email as "URGENT"

Preventive Measures

Regular Maintenance

Weekly:

  • Restart HarborDB to clear memory
  • Clear temporary export files
  • Backup important connection settings

Monthly:

  • Update HarborDB and PostgreSQL
  • Review and optimize slow queries
  • Clean up unused connections

Best Practices to Avoid Issues

  1. Connection Management:

    • Use meaningful connection names
    • Regularly test connections
    • Remove unused connections

  2. Query Development:

    • Always use LIMIT during exploration
    • Test with EXPLAIN before running large queries
    • Save complex queries for reuse

  3. System Maintenance:

    • Keep macOS updated
    • Regular Time Machine backups
    • Monitor disk space

Additional Resources

Back to categoryBack to Documentation

Was this helpful?

Help us improve this documentation by providing feedback.

Report IssueContact SupportEdit this page