Troubleshooting

This guide covers common issues you may encounter while using the Servers App and how to resolve them.

Connection Issues

Issue: Connection Test Fails

Symptoms:

• "Test Connection" button shows failure
• Red error message appears in dialog
• Cannot verify server connectivity

Possible Causes:

• Server URL is incorrect or has a typo
• Server is not running or not accessible
• Network firewall blocking the connection
• SSL certificate issues with HTTPS connections

Solutions:

1. Verify the server URL:

   Correct: https://localhost:7443
   Wrong:   http://localhost:7443 (missing 's')
   Wrong:   https://localhost:7443/ (trailing slash)
   

2. Check if the server is running:

   # For local development servers
   yarn docker:logs
   

3. Test connectivity manually:

   curl -k https://localhost:7443/health
   

4. For SSL certificate issues, ensure your browser trusts the development certificate or use the appropriate certificate authority.

Issue: Server Shows "Offline" Status

Symptoms:

• Server appears in list but shows offline
• Replication is not working
• Data not syncing across devices

Possible Causes:

• Server went down after configuration
• Network connectivity changed
• Server URL changed

Solutions:

1. Click the Edit (pencil) icon on the server row
2. Click Test Connection to diagnose the issue
3. Update the URL if the server moved
4. Contact your administrator if the server is down

Authentication Issues

Issue: Verification Code Not Received

Symptoms:

• Email with verification code never arrives
• Waited several minutes with no email
• Checked spam folder with no results

Possible Causes:

• Email address entered incorrectly
• Server's email service is down
• Email filtered by corporate security

Solutions:

1. Double-check your email address - Look for typos
2. Check spam/junk folders - Verification emails may be filtered
3. Wait a few minutes - Email delivery can be delayed
4. Try again - Click "Resend Code" if available
5. Contact support if the issue persists

Issue: Authentication Token Expired

Symptoms:

• Was previously authenticated but now shows "Not Authenticated"
• Replication stopped working
• Need to log in again

Possible Causes:

• JWT token expired (normal behavior)
• Server invalidated the session
• Token was manually revoked

Solutions:

1. Click the Login button to re-authenticate
2. Complete the email verification flow again
3. Your session will be restored with a new token

Issue: Login Page Shows Error

Symptoms:

• Red error banner on login page
• Cannot complete authentication
• "Invalid code" or similar message

Possible Causes:

• Verification code was entered incorrectly
• Code expired (usually after 10 minutes)
• Server authentication service issues

Solutions:

1. Check the code carefully - Ensure no extra spaces
2. Request a new code if more than 10 minutes passed
3. Verify the server is healthy using connection test

Configuration Issues

Issue: Cannot Delete Server

Symptoms:

• Delete button is disabled
• Warning message appears
• Server cannot be removed

Possible Causes:

• Server is currently set as active
• Server has pending replication operations

Solutions:

1. Set a different server as active first
2. Then delete the unwanted server

Flow: Set Another Active → Delete Original

Issue: Changes Not Saving

Symptoms:

• Server configuration reverts after saving
• Dialog closes but changes are lost
• No error message displayed

Possible Causes:

• Validation error not clearly shown
• Browser storage issue
• Concurrent modification conflict

Solutions:

1. Check all required fields are filled:

   • Server Name (required)
   • URL (required)
   • Database Name (required)

2. Clear browser storage and try again:

   DevTools → Application → Clear Site Data
   

3. Refresh the page and re-enter the configuration

Data Sync Issues

Issue: Data Not Syncing

Symptoms:

• Changes made on one device don't appear on another
• Sync indicator shows no activity
• Data is only available locally

Possible Causes:

• No active server configured
• Not authenticated with the server
• Server replication endpoint issues

Solutions:

1. Verify an active server exists:

   • Look for the star icon in the server list
   • If no star, set a server as active

2. Check authentication status:

   • Look for "Authenticated" badge
   • If "Not Authenticated", click Login

3. Verify server health:

   • Use Test Connection in edit dialog
   • Check server logs for errors

Issue: Duplicate Servers Appearing

Symptoms:

• Same server appears multiple times in list
• Confusion about which one is active
• Possible from import or migration

Solutions:

1. Identify the correct server (check URLs and names)
2. Set the correct one as active
3. Delete the duplicate entries
4. Verify only one remains

UI Issues

Issue: Server List Not Loading

Symptoms:

• Spinning loader that never completes
• Blank screen where server list should be
• "Loading..." text persists

Possible Causes:

• Local storage corruption
• JavaScript error
• App state issue

Solutions:

1. Refresh the page: Cmd/Ctrl+R

2. Check browser console for errors:

   DevTools → Console tab → Look for red errors
   

3. Clear application data:

   DevTools → Application → Storage → Clear Site Data
   

4. Restart the application (for Electron)

Issue: Keyboard Shortcuts Not Working

Symptoms:

• Cmd/Ctrl+N doesn't open Add Server
• Cmd/Ctrl+S doesn't trigger sync
• Shortcuts work in other apps

Possible Causes:

• Focus is not on the Servers App
• Another app capturing the shortcuts
• Shortcut conflict

Solutions:

1. Click anywhere in the Servers App to ensure it has focus
2. Check if another application is intercepting shortcuts
3. Use the button alternatives instead of shortcuts

Getting Help

If you cannot resolve your issue using this guide:

1. Check the FAQ for additional answers

2. Gather diagnostic information:

   • Browser and version
   • Operating system
   • Steps to reproduce the issue
   • Screenshots of error messages
   • Browser console output

3. Report the issue with the collected information to support

4. Check server logs if you have administrator access:

   yarn docker:logs