Troubleshooting
Common Issues
Troubleshoot connection errors, performance issues, UI problems, and other common MongoDash challenges
Common Issues
This guide helps you diagnose and resolve common problems encountered when using MongoDash.
Connection Issues
Cannot Connect to MongoDB
Symptoms:
- "Connection timeout" error
- "Authentication failed" message
- "Network error" when testing connection
Solutions:
Verify connection string format:
mongodb+srv://username:password@cluster.mongodb.net/database- Ensure no spaces in the URI
- Check username and password are correct
- Verify cluster hostname
Check IP allowlist:
- For MongoDB Atlas, add MongoDash IPs to allowlist
- Go to Atlas > Network Access > Add IP Address
- Add:
52.1.1.1and52.1.1.2(example IPs)
Verify authentication:
- Confirm database user exists
- Check user has read permissions
- Verify password is correct (no special characters issues)
Test connectivity:
- Use
mongoshto connect from your local machine - If local connection works, issue is with MongoDash access
- If local connection fails, issue is with your MongoDB configuration
For MongoDB Atlas connections, ensure you're using the SRV connection string format, not the legacy format.
Connection Drops Frequently
Symptoms:
- "Connection lost" messages during usage
- Queries fail intermittently
- Must reconnect frequently
Solutions:
- Check firewall settings - Ensure persistent connections are allowed
- Verify network stability - Test your internet connection
- Increase timeout settings - In connection settings, increase socket timeout
- Use connection pooling - Enable in advanced connection options
- Check MongoDB server status - Verify server isn't restarting or experiencing issues
SSH Tunnel Connection Fails
Symptoms:
- "SSH connection failed" error
- "Unable to establish tunnel" message
Solutions:
Verify SSH credentials:
- Correct hostname and port (usually 22)
- Valid username
- Private key is in correct format (OpenSSH)
Check SSH key permissions:
chmod 600 ~/.ssh/id_rsaTest SSH connection manually:
ssh -i ~/.ssh/id_rsa user@hostnameVerify tunnel configuration:
- Correct local and remote ports
- MongoDB is accessible from SSH host
Performance Issues
Slow Query Execution
Symptoms:
- Queries take longer than expected
- Timeout errors on large collections
- UI becomes unresponsive during queries
Solutions:
Add indexes:
- Identify frequently queried fields
- Create indexes on those fields
- Use compound indexes for multi-field queries
// Create index via MongoDB
db.collection.createIndex({ "field": 1 })Optimize query filters:
- Use equality matches before range queries
- Avoid regex without anchors (
^start) - Limit result sets with
limitparameter
Use projection:
- Only fetch needed fields
- Reduces data transfer and processing time
{
"filter": { "status": "active" },
"projection": { "name": 1, "email": 1 }
}Check query explain plan:
- Click "Explain" button in query editor
- Look for
COLLSCAN(bad) vsIXSCAN(good) - Aim for low
executionTimeMillis
Dashboard Loading Slowly
Symptoms:
- Dashboards take 10+ seconds to load
- Widgets show "Loading..." for extended periods
- Browser becomes sluggish
Solutions:
- Reduce widget count - Limit to 10-15 widgets per dashboard
- Optimize widget queries - Ensure queries use indexes
- Increase refresh interval - Change from 30s to 60s or higher
- Use aggregation - Pre-aggregate data instead of fetching all documents
- Enable caching - Turn on query caching for static data
- Upgrade plan - Higher tiers have better performance limits
Large Collection Loading Issues
Symptoms:
- Collection won't load
- "Memory exceeded" errors
- Browser crashes when viewing collection
Solutions:
Use filters to limit results:
- Don't load entire collection
- Apply date range or status filters
- Use pagination (limit to 100-500 documents)
Create custom views:
- Save filtered views for common queries
- Use indexes on view filters
Use aggregation:
- Get summary data instead of all documents
- Count and statistics are faster than full scans
Collections with millions of documents should always be accessed with filters. Loading all documents can cause browser crashes.
Authentication & Access Issues
Cannot Log In
Symptoms:
- "Invalid credentials" error
- Two-factor authentication not working
- "Account locked" message
Solutions:
Forgot Password:
- Click "Forgot Password" on login page
- Enter your email address
- Check email for reset link (check spam folder)
- Reset password and try logging in
2FA Issues:
- Ensure phone time is synchronized
- Try backup codes if QR code fails
- Contact support to disable 2FA if locked out
Account Locked:
- Wait 30 minutes for automatic unlock
- Or contact support for manual unlock
Insufficient Permissions
Symptoms:
- "Access denied" errors
- Features grayed out or missing
- "You don't have permission" messages
Solutions:
Check your role:
- Go to Workspace Settings > Team Members
- Find your name and view assigned role
- Viewer, Editor, or Admin
Request permissions:
- Contact workspace admin
- Request role upgrade if needed
- Or request specific feature access
Verify plan tier:
- Some features require paid plans
- Check plan comparison for feature availability
Session Expires Too Quickly
Symptoms:
- Logged out frequently
- "Session expired" messages
- Must re-authenticate multiple times per day
Solutions:
- Enable "Remember Me" - Check box at login
- Adjust session timeout - Admins can change in workspace settings
- Check browser settings - Ensure cookies are enabled
- Disable aggressive privacy settings - May block session cookies
UI and Display Issues
Dashboard Not Displaying Correctly
Symptoms:
- Widgets overlapping
- Layout broken or misaligned
- Missing elements
Solutions:
Clear browser cache:
Chrome: Ctrl/Cmd + Shift + Delete
Firefox: Ctrl/Cmd + Shift + Delete
Safari: Cmd + Option + EHard refresh:
Windows: Ctrl + F5
Mac: Cmd + Shift + RTry different browser:
- Test in Chrome, Firefox, or Safari
- Identifies if issue is browser-specific
Disable browser extensions:
- Ad blockers can interfere with dashboards
- Privacy extensions may block resources
- Disable temporarily to test
Charts Not Rendering
Symptoms:
- Empty chart widgets
- "Unable to load chart" errors
- Charts show "No data" despite data existing
Solutions:
- Check data query - Verify query returns data
- Validate chart configuration - Ensure X and Y axes are correctly mapped
- Check data types - Charts require numeric values for numbers, dates for time series
- Review console errors - Press F12 to open developer console
- Update chart type - Some data doesn't work with certain chart types
Mobile Display Problems
Symptoms:
- UI elements too small on mobile
- Layout doesn't fit screen
- Features not accessible on mobile
Solutions:
- Use responsive layout - Switch to mobile-optimized view in settings
- Rotate device - Landscape mode for better dashboard viewing
- Zoom appropriately - Pinch to zoom on touchscreen
- Use mobile app - Download iOS/Android app for better mobile experience
Data and Query Issues
Query Returns No Results
Symptoms:
- Query returns empty result set
- Expected data not showing
- Filter seems to match nothing
Solutions:
Verify filter syntax:
// Correct
{ "status": "active" }
// Incorrect (case sensitive)
{ "status": "Active" }Check field names:
- Field names are case-sensitive
- Verify spelling matches database schema
- Check for nested field paths
Test without filters:
- Remove all filters to see all documents
- Add filters back one at a time
- Identifies which filter causes issue
Check data types:
// String vs Number
{ "age": "25" } // Won't match if age is number
{ "age": 25 } // Correct for numeric fieldCannot Update Document
Symptoms:
- "Update failed" error
- Changes don't save
- "Validation error" messages
Solutions:
- Check permissions - Ensure you have write access
- Verify validation rules - Document may violate schema validation
- Check for conflicts - Another user may have updated document
- Validate JSON syntax - Ensure update operation is valid JSON
- Check field types - Cannot set string field to number value
Import Fails
Symptoms:
- CSV/JSON import errors
- "Invalid format" messages
- Partial data imported
Solutions:
Validate file format:
- CSV: Ensure proper comma separation, quoted strings
- JSON: Validate with JSONLint
- Excel: Save as CSV first
Check encoding:
- Use UTF-8 encoding
- Avoid special characters in field names
- Ensure proper line endings (Unix vs Windows)
Review field mapping:
- Map CSV columns to correct fields
- Verify data types are compatible
- Check for required fields
Import in batches:
- Large files may timeout
- Split into smaller files (1000-5000 rows)
- Import incrementally
Billing and Subscription Issues
Payment Declined
Symptoms:
- "Payment failed" notification
- Credit card not accepted
- Subscription shows as past due
Solutions:
- Verify card details - Check expiration date, CVV code
- Check card limit - Ensure sufficient funds
- Contact bank - Authorize international transactions if needed
- Try different card - Add alternative payment method
- Use ACH/wire transfer - For large annual payments
Features Not Available After Upgrade
Symptoms:
- Upgraded plan but features still locked
- "Upgrade required" messages persist
- Limits haven't increased
Solutions:
Refresh browser:
- Hard refresh (Ctrl+F5 / Cmd+Shift+R)
- Clear cache
- Log out and log back in
Verify payment processed:
- Check billing dashboard
- Ensure payment wasn't declined
- Review email for confirmation
Wait for propagation:
- Changes can take up to 5 minutes
- Check back after brief delay
Contact support:
- If issue persists after 30 minutes
- Provide workspace ID and invoice number
Browser Compatibility
Recommended Browsers
| Browser | Minimum Version | Recommended |
|---|---|---|
| Chrome | 90+ | Latest |
| Firefox | 88+ | Latest |
| Safari | 14+ | Latest |
| Edge | 90+ | Latest |
Unsupported Features
Some features may not work in older browsers:
- Real-time updates (requires WebSocket support)
- Advanced visualizations (requires Canvas API)
- File drag-and-drop (requires modern File API)
Getting Additional Help
Before Contacting Support
Gather this information:
- Error messages - Full text of any errors
- Screenshots - Capture the issue visually
- Steps to reproduce - What you did before the error
- Browser and OS - Version information
- Workspace ID - Found in workspace settings
- Timeframe - When the issue started
Contact Methods
- Documentation - Check docs.mongodash.com
- Community Forum - community.mongodash.com
- Email Support - support@mongodash.com
- Live Chat - Business and Enterprise plans (in-app)
- Phone Support - Enterprise plans only
Response Times
| Plan | Response Time | Support Hours |
|---|---|---|
| Free | N/A | Community only |
| Team | 24 hours | Business hours |
| Business | 4 hours | Extended hours |
| Enterprise | 1 hour | 24/7 |
For critical issues affecting production systems, Enterprise customers can call our 24/7 emergency hotline.
What's Next?
- FAQ - Frequently asked questions
- Connection Troubleshooting - Detailed connection diagnostics
- Query Performance - Optimize slow queries