Troubleshooting

Purpose

This reference guide covers common issues you might encounter while using EvoNEST and how to solve them.

How to use this guide: Find your issue in the table of contents and jump to the solution.

Docker and Container Issues
Application Won't Start
Database Connection Problems
Login and Authentication Issues
File Upload Errors
Performance and Slow Loading
Browser Compatibility
Data Entry Problems
Getting Help

Docker and container issues

Problem: Docker desktop won't start

Symptoms:

Docker icon shows error
"Docker is not running" message

Solutions:

Restart Docker Desktop
- Completely quit Docker Desktop (right-click icon → Quit)
- Wait 10 seconds
- Restart it
Check system resources
- Ensure you have enough RAM (8GB+ recommended)
- Close other memory-intensive applications
- Restart your computer

On Windows: WSL 2 issues

powershell

# Update WSL
wsl --update

# Restart WSL
wsl --shutdown

On Mac: Permissions issue
- Go to System Preferences → Security & Privacy
- Allow Docker in Privacy tab
Reinstall Docker Desktop
- Uninstall Docker Desktop
- Download fresh installer from docker.com
- Reinstall

Problem: containers won't start

Symptoms:

docker compose up fails
Containers show "Exited" status

Check container status:

bash

docker compose -f docker-compose.dev.yml ps

View logs:

bash

docker compose -f docker-compose.dev.yml logs

Solutions:

Port already in use
Error message:
```
Error: bind: address already in use
```
Find what's using the port:
Mac/LinuxWindows (PowerShell)
bash
```
lsof -i :3005
lsof -i :27019
```
bash
```
netstat -ano | findstr :3005
netstat -ano | findstr :27019
```
Solutions:
- Stop the conflicting application
- OR change ports in docker-compose.dev.yml
Out of disk space
Check disk space:
bash
```
df -h  # Mac/Linux
```
Clean Docker:
bash
```
docker system prune -a --volumes
```
This Deletes Data!
The prune command removes all stopped containers and volumes. Make sure to backup your data first!

Corrupted volumes

Reset everything:

bash

docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up --build -d

Problem: changes to code not reflected

Symptom:

You edit code but don't see changes
Old version still running

Solutions:

Restart containers:

bash

docker compose -f docker-compose.dev.yml restart

Rebuild containers:

bash

docker compose -f docker-compose.dev.yml up --build -d

Clear node_modules volume:

bash

docker compose -f docker-compose.dev.yml down -v
docker compose -f docker-compose.dev.yml up --build -d

Application won't start

Problem: "ready in x.xs" never appears

Symptoms:

Containers are running
But application won't load
Logs show errors or hang

Check logs:

bash

docker compose -f docker-compose.dev.yml logs evonest_backbone_dev

Common causes:

Node modules not installed

Error in logs:

Error: Cannot find module 'next'

Fix:

bash

docker compose -f docker-compose.dev.yml down
docker compose -f docker-compose.dev.yml up --build -d

MongoDB not ready
Symptom: Errors about database connection
Fix: Wait longer (MongoDB takes 30-60 seconds on first start)
bash
```
# Watch logs
docker compose -f docker-compose.dev.yml logs -f
```
Environment variables missing
Check you have:
- .env.local with NEXTAUTH_SECRET
- .env.development with MONGODB_URI
Verify:
bash
```
# Mac/Linux
cat .env.local
cat .env.development

# Windows
type .env.local
type .env.development
```
Port forwarding issue
Try accessing different address:
- http://127.0.0.1:3005
- http://0.0.0.0:3005

Database connection problems

Problem: "cannot connect to MongoDB"

Symptoms:

Error messages about database
Blank pages or infinite loading

Solutions:

Check MongoDB is running:

bash

docker compose -f docker-compose.dev.yml ps mongo_dev

Should show "Up" status.

Verify credentials match:

In .env.development:

txt

MONGODB_URI=mongodb://evonest_user:MyPassword123@mongo_dev:27017

In docker-compose.dev.yml:

yaml

MONGO_INITDB_ROOT_USERNAME: evonest_user
MONGO_INITDB_ROOT_PASSWORD: MyPassword123

Must match exactly!

Restart MongoDB:

bash

docker compose -f docker-compose.dev.yml restart mongo_dev

Reset MongoDB:

bash

docker compose -f docker-compose.dev.yml down
docker volume rm evonest-backbone_evonestdev_node_modules
docker compose -f docker-compose.dev.yml up -d

Problem: data disappeared

Symptom:

Had data, now it's gone
Empty samples/traits tables

Possible causes:

Switched databases
- Check which database is active (User Profile menu)
- Switch back to correct database
Ran docker compose down -v
- The -v flag deletes volumes (data storage)
- Data is permanently lost if no backup
MongoDB was reset
- Check if someone ran a migration script

Prevention:

Regular backups:

bash

# Export your data regularly
# Use the "Export" feature in EvoNEST
# Or backup MongoDB:
docker exec evonest_mongodb_dev mongodump --out /backup

Problem: can't log in with admin/pass

Solutions:

Check credentials:
- Username: admin (lowercase)
- Password: pass (lowercase)
- No spaces

Verify NEXTAUTH_SECRET is set:

bash

# Mac/Linux
cat .env.local | grep NEXTAUTH_SECRET

# Windows
type .env.local | findstr NEXTAUTH_SECRET

Should show a long random string.

Clear browser cache:
- Press Ctrl+Shift+Delete (or Cmd+Shift+Delete on Mac)
- Clear cookies and cache
- Try again
Try incognito/private mode:
- Open private browsing window
- Try logging in

Restart application:

bash

docker compose -f docker-compose.dev.yml restart

Problem: logged out automatically

Symptoms:

Keep getting logged out
Session expires quickly

Solutions:

Check NEXTAUTH_SECRET is set correctly
Browser cookies disabled:
- Enable cookies in browser settings
- Allow cookies for localhost
System clock wrong:
- Check your computer's date/time
- JWT tokens use timestamps

File upload errors

Problem: "failed to upload file"

Solutions:

Check file size:
- Max size typically 10-50MB
- Compress large images
- Split large files
Check file format:
- Supported: JPEG, PNG, PDF, XLSX, CSV
- Unsupported: EXE, DMG, certain proprietary formats

Check disk space:

bash

# Check Docker has space
docker system df

Check permissions:

bash

# Linux/Mac: Check file_storage folder
ls -la file_storage_dev

Restart application:

bash

docker compose -f docker-compose.dev.yml restart

Problem: images show broken/not loading

Solutions:

Clear browser cache
Check file was actually uploaded:
- Go to Mongo Express: http://localhost:8081
- Check files collection
- Verify entry exists
Check file_storage directory:
bash
```
ls file_storage_dev/
```
Files should be there.
Try re-uploading the file

Performance and slow loading

Problem: EvoNEST is very slow

Solutions:

Give Docker more resources:
Docker Desktop → Settings → Resources:
- Increase Memory to 4GB+
- Increase CPUs to 2-4
- Restart Docker
Too much data loaded:
- Use filters to reduce displayed data
- Paginate large tables
- Export old data and archive
Check system resources:
- Close unnecessary applications
- Restart your computer

Database indexes:

Run the index migration:

bash

node src/migrations/011_setup_indexes/migration.js

Problem: first page load is slow

Normal behavior:

First load: 5-10 seconds (Docker startup)
Subsequent loads: 1-2 seconds

If consistently slow:

Development mode is slower:
- Development mode rebuilds on changes
- Normal in development

Use production mode:

bash

docker compose -f docker-compose.yml up -d

Browser compatibility

Problem: features not working in my browser

Recommended browsers:

✅ Chrome/Chromium 90+ (best support)
✅ Firefox 88+
✅ Edge 90+
✅ Safari 14+

Solutions:

Update your browser to latest version
Enable JavaScript
Disable browser extensions:
- Try in incognito/private mode
- Ad blockers can interfere
Clear cache and cookies

Problem: interface looks broken

Symptoms:

Buttons misaligned
Text overlapping
Missing styles

Solutions:

Hard refresh:
- Windows/Linux: Ctrl+Shift+R
- Mac: Cmd+Shift+R
Clear cache:
- Ctrl+Shift+Delete → Clear cache
Check browser console:
- Press F12
- Look for CSS/JavaScript errors

Data entry problems

Problem: can't create sample - "type not found"

Cause: Types not configured

Solution:

Go to Settings → Configuration
Add sample types, trait types
Save configuration
Try creating sample again

Problem: sample ID not auto-generating

Check:

Settings → Main Settings
Verify ID generation rules are set
Try leaving Name field blank
Save

Manual workaround:

Enter custom ID manually in Name field

Problem: units not showing for traits

Cause: Trait type doesn't have unit configured

Solution:

Settings → Types → Trait Types
Find the trait type
Edit it
Add Unit field (e.g., μm, MPa)
Save

Problem: can't link sample to experiment

Possible causes:

Wrong database:
- Sample and experiment must be in same database
- Check active database in User Profile
Search not finding sample:
- Type exact sample name
- Try filtering by type/family first
Sample doesn't exist:
- Verify sample was actually created
- Check Samples page

Getting help

Before asking for help

Gather this information:

What you were trying to do
What happened instead
Error messages (exact text)
Browser and version
Operating system

Docker logs:

bash

docker compose -f docker-compose.dev.yml logs > logs.txt

Browser console errors

Press F12 (or Cmd+Option+I on Mac)
Go to Console tab
Screenshot any red errors
Include with help request

Where to get help

Documentation:
GitHub Issues:
- github.com/daniele-liprandi/EvoNEST-backbone/issues
- Search existing issues first
- Create new issue with template
Contact:
- See README for contact information
- Include logs and error messages

Complete reset (last resort)

If nothing works, start fresh:

Warning: Deletes All Data!

This will delete all your samples, traits, experiments, and files. Backup first!

Step 1: export your data

Go to each section (Samples, Traits, Experiments)
Use Export function
Download CSV/Excel files
Save files somewhere safe

Step 2: complete reset

bash

# Stop and remove everything
docker compose -f docker-compose.dev.yml down -v

# Remove Docker images
docker rmi evonest-backbone-node

# Remove any orphaned volumes
docker volume prune

# Start fresh
docker compose -f docker-compose.dev.yml up --build -d

Step 3: reconfigure

Log in with admin/pass
Go through Module 4 (Configuration) again
Import your saved data (if import feature available)

Quick command reference

Problem	Command
Restart everything	`docker compose -f docker-compose.dev.yml restart`
View logs	`docker compose -f docker-compose.dev.yml logs -f`
Check status	`docker compose -f docker-compose.dev.yml ps`
Rebuild	`docker compose -f docker-compose.dev.yml up --build -d`
Complete reset	`docker compose -f docker-compose.dev.yml down -v`
Clean Docker	`docker system prune`

Still having issues?

If you've tried everything in this guide and still have problems:

Document the issue:
- What you tried
- What happened
- Error messages
- Logs
Search GitHub issues:
- Someone might have had the same problem
Create an issue:
- Use the issue template
- Provide complete information
- Attach logs if possible
Ask in the workshop:
- If attending a workshop, ask the instructor

Preventive measures

Avoid future problems:

✅ Regular backups - Export data weekly
✅ Keep Docker updated - Update Docker Desktop
✅ Monitor disk space - Keep 10GB+ free
✅ Document your setup - Note any custom configurations
✅ Use version control - Keep config files in git
✅ Test before deploying - Try changes in development first

Troubleshooting ​

Table of contents ​

Docker and container issues ​

Problem: Docker desktop won't start ​

Problem: containers won't start ​

Problem: changes to code not reflected ​

Application won't start ​

Problem: "ready in x.xs" never appears ​

Database connection problems ​

Problem: "cannot connect to MongoDB" ​

Problem: data disappeared ​

Login and authentication issues ​

Problem: can't log in with admin/pass ​

Problem: logged out automatically ​

File upload errors ​

Problem: "failed to upload file" ​

Problem: images show broken/not loading ​

Performance and slow loading ​

Problem: EvoNEST is very slow ​

Problem: first page load is slow ​

Browser compatibility ​

Problem: features not working in my browser ​

Problem: interface looks broken ​

Data entry problems ​

Problem: can't create sample - "type not found" ​

Problem: sample ID not auto-generating ​

Problem: units not showing for traits ​

Problem: can't link sample to experiment ​

Getting help ​

Before asking for help ​

Browser console errors ​

Where to get help ​

Complete reset (last resort) ​

Step 1: export your data ​

Step 2: complete reset ​

Step 3: reconfigure ​

Quick command reference ​

Still having issues? ​

Preventive measures ​

Troubleshooting

Table of contents

Docker and container issues

Problem: Docker desktop won't start

Problem: containers won't start

Problem: changes to code not reflected

Application won't start

Problem: "ready in x.xs" never appears

Database connection problems

Problem: "cannot connect to MongoDB"

Problem: data disappeared

Login and authentication issues

Problem: can't log in with admin/pass

Problem: logged out automatically

File upload errors

Problem: "failed to upload file"

Problem: images show broken/not loading

Performance and slow loading

Problem: EvoNEST is very slow

Problem: first page load is slow

Browser compatibility

Problem: features not working in my browser

Problem: interface looks broken

Data entry problems

Problem: can't create sample - "type not found"

Problem: sample ID not auto-generating

Problem: units not showing for traits

Problem: can't link sample to experiment

Getting help

Before asking for help

Browser console errors

Where to get help

Complete reset (last resort)

Step 1: export your data

Step 2: complete reset

Step 3: reconfigure

Quick command reference

Still having issues?

Preventive measures