Common issues and solutions for Nexo Share.

Installation Issues

ClamAV Container Won’t Start

Symptoms: Nexoshare_clamav keeps restarting or is unhealthy.

Causes:

Insufficient RAM (ClamAV needs ~2GB)
Virus definitions download failed
Corrupted volume

Solutions:

Check RAM:

free -h

If less than 4GB total, ClamAV will struggle.

Check logs:

docker compose logs clamav

Look for “Database load failed” or memory errors.

Increase start period: Edit docker-compose.yml:

clamav:
  healthcheck:
    start_period: 240s  # Give more time for definitions download

Reset ClamAV data:

docker compose down
rm -rf ./clamav/*
docker compose up -d

Disable virus scanning (not recommended): Settings → System → Uncheck “Enforce Virus Scan”

Database Connection Failed

Symptoms: “Waiting for database” or 500 errors on startup.

Solutions:

Check PostgreSQL is running:

docker compose ps postgres

Verify password matches: Compare DB_PASSWORD in Nexo Share and postgres environment variables.
Check logs:

docker compose logs postgres

Reset database (deletes all data):

docker compose down
rm -rf ./data/*
docker compose up -d

Port Already in Use

Symptoms: “Port 3000 is already allocated” error.

Solution: Change port mapping in docker-compose.yml:

ports:
  - "8080:3000"  # Use 8080 instead

Access via http://localhost:8080.

Frontend Build Not Found

Symptoms: Application shows “Frontend build not found” or 404 on all pages.

Solution: This indicates a problem with the Docker image. Pull latest:

docker compose pull
docker compose up -d

Cause: Default admin account not created.

Solution:

Check logs: docker compose logs nexoshare
Look for “✅ DB Initialized” message
If not present, reset database (see above)
Default credentials: [email protected] / admin123 (change immediately)
Change password immediately after first login

Cookies Not Working

Symptoms: Login succeeds but redirects back to login page.

Causes:

sameSite: strict with HTTP (needs HTTPS)
CORS issues
Browser blocking cookies

Solutions:

Enable HTTPS (required for secure cookies)
Check ALLOWED_ORIGINS:

ALLOWED_ORIGINS: "http://localhost:3000"  # Must match your URL exactly

Disable secure cookies temporarily (development only): Settings → General → Uncheck “Secure Cookies”
Clear browser cache and cookies

2FA Code Not Working

Symptoms: “Invalid code” error during 2FA verification.

Causes:

Phone time not synced
Wrong app (not TOTP-compatible)
Used backup code as TOTP code

Solutions:

Sync phone time: Settings → Date & Time → Automatic
Use authenticator app: Google Authenticator, Authy, Microsoft Authenticator
Try backup code: Enter one of your 8 backup codes instead
Admin reset (admin only):
- Settings → Users → Click user → Reset 2FA

Passkey Registration Fails

Symptoms: “Registration failed” or nothing happens when clicking “Register”.

Causes:

HTTPS not enabled
RP_ID doesn’t match domain
Browser doesn’t support passkeys

Solutions:

Enable HTTPS (passkeys require secure context)
Fix RP_ID:

RP_ID: "share.company.com"  # Must match your domain exactly (no https://)
ORIGIN: "https://share.company.com"  # Must include https://

Check browser: Chrome 67+, Firefox 60+, Safari 13+, Edge 18+
Clear application storage: Browser DevTools → Application → Clear Storage

Upload Issues

Upload Fails Immediately

Symptoms: “Upload failed” or “Chunk write failed” error.

Causes:

File too large
Disk full
Permission issue on uploads folder

Solutions:

Check file size: Settings → System → Check Max File Size
Check disk space:

df -h

Check folder permissions:

ls -la ./uploads
# Should be writable
chmod -R 755 ./uploads

Check logs:

docker compose logs nexoshare | grep -i error

Upload Stalls at 99%

Symptoms: Progress bar reaches 99% but never completes.

Causes:

Virus scan timeout
Backend processing taking too long
Network interruption

Solutions:

Wait longer: Virus scanning large files takes time
Check ClamAV: docker compose logs clamav
Restart containers:

docker compose restart

“Virus detected” Error (False Positive)

Symptoms: Upload rejected with virus warning for safe files.

Causes:

ClamAV false positive
File contains suspicious patterns
Outdated virus definitions

Solutions:

Update ClamAV:

docker compose restart clamav

Wait 5 minutes for virus definitions to update.

Temporary workaround: Settings → System → Uncheck “Enforce Virus Scan” (Not recommended for production)
Report false positive to ClamAV: https://www.clamav.net/reports/fp

Upload Limit Reached

Symptoms: “Upload limit exceeded” or “Share limit exceeded”.

Causes:

System-wide max size exceeded
Reverse share specific limit reached

Solutions:

Increase system limit: Settings → System → Max File Size
Split files: Upload in multiple shares
Clean old shares: Delete expired/unneeded shares to free space

Download Issues

Download Button Does Nothing

Symptoms: Clicking download doesn’t start download.

Causes:

Browser popup blocker
Share expired
Download limit reached

Solutions:

Check share status: Owner can see in “My Shares” if expired
Allow popups for the site
Try different browser
Check logs:

docker compose logs nexoshare | grep -i download

ZIP Download Corrupted

Symptoms: “Archive is corrupted” or “Cannot extract” error.

Causes:

Download interrupted
Storage issue
Memory pressure

Solutions:

Try individual file downloads instead of ZIP
Restart containers:

docker compose restart

Check disk space:

df -h

Download Link Shows 410 Error

Symptoms: “This share is no longer available”.

Causes:

Share expired
Download limit reached
Share deleted by owner

Solutions:

Contact the sender to reshare
Owner can extend expiration or increase download limit

Email Issues

Test Email Fails

Symptoms: “Could not send email” or timeout error.

Causes:

Wrong SMTP credentials
Firewall blocking port
Server requires different security settings

Solutions:

Double-check credentials: Username, password, server
Try different port:
- 587 with STARTTLS
- 465 with SSL
Check firewall:

telnet smtp.office365.com 587
# Should connect successfully

Enable “Allow Local IPs” if SMTP is on same network
Check logs:

docker compose logs nexoshare | grep -i smtp

Emails Not Received

Symptoms: Test succeeds but recipients don’t get emails.

Causes:

Emails in spam folder
Wrong “From” address
Rate limiting by email provider

Solutions:

Check spam folder
Verify “From” address: Settings → SMTP → From field
Add SPF/DKIM records (ask your email admin)
Check email server logs for bounce messages

Email Shows Broken Images

Symptoms: Logo or images missing in emails.

Causes:

appUrl not set correctly
Logo URL is private/localhost

Solutions:

Set App URL: Settings → General → App URL
```
https://share.company.com
```
Use public logo URL or upload via Settings → General

Performance Issues

Slow Upload Speeds

Causes:

CPU throttling
Slow disk (HDD instead of SSD)
Virus scanning overhead

Solutions: 2. Check CPU: docker stats 3. Use SSD/NVMe storage for uploads folder 4. Disable media compression: Settings → System → No Compression for Media

Application Unresponsive

Symptoms: Timeouts, “Server error”, or very slow responses.

Causes:

Memory exhaustion
Too many concurrent uploads
Database performance issues

Solutions:

Check resource usage:

docker stats

Restart services:

docker compose restart

Increase memory limits in docker-compose.yml:

Nexoshare:
  deploy:
    resources:
      limits:
        memory: 4G

Check database size:

docker compose exec postgres psql -U nexoshare -d nexoshare -c "SELECT pg_size_pretty(pg_database_size('nexoshare'));"

High CPU Usage

Symptoms: Server sluggish, CPU at 100%.

Causes:

Multiple ZIP downloads
ClamAV scanning
Too many concurrent users

Solutions:

Reduce ZIP compression: Settings → System → Compression Level = 0
Limit concurrent operations: Built-in queuing handles this automatically
Upgrade server if consistently high load

SSL/HTTPS Issues

Certificate Errors

Symptoms: Browser shows “Not secure” or certificate warning.

Causes:

Self-signed certificate
Certificate expired
Wrong domain in certificate

Solutions:

Use Let’s Encrypt (see Production Deployment guide)
Renew certificate:

sudo certbot renew
sudo systemctl restart nginx

Check certificate validity:

sudo certbot certificates

Mixed Content Warnings

Symptoms: Some resources load over HTTP instead of HTTPS.

Causes:

appUrl set to HTTP instead of HTTPS
Reverse proxy not passing correct headers

Solutions:

Update appUrl: Settings → General → App URL
```
https://share.company.com
```

Configure reverse proxy to set:

proxy_set_header X-Forwarded-Proto $scheme;

Database Issues

“Connection refused” Errors

Symptoms: Can’t connect to PostgreSQL.

Solution:

docker compose logs postgres
docker compose restart postgres

Database Corruption

Symptoms: Random errors, data loss, startup failures.

Solutions:

Stop services:

docker compose down

Backup existing data:

cp -r ./data ./data_backup

Try recovery:

docker compose up -d postgres
docker compose exec postgres pg_resetwal /var/lib/postgresql/data

Last resort - restore from backup:

# Restore from SQL dump
docker compose exec -T postgres psql -U nexoshare nexoshare < backup.sql

Diagnostic Commands

View All Logs

docker compose logs -f

Check Container Health

docker compose ps

Inspect Container

docker compose exec Nexo Share sh
# Now inside container
ls /app/backend/uploads
exit

Check Database Connection

docker compose exec postgres psql -U nexoshare -d nexoshare -c "SELECT NOW();"

Test Network Connectivity

docker compose exec nexoshare wget -O- http://google.com

Export Full Logs

docker compose logs > Nexo_Share_logs.txt

Getting Help

If none of these solutions work:

Check logs for specific error messages
Search existing issues: https://github.com/minemap-nl/nexoshare/issues
Create new issue with:
- Docker version: docker --version
- Compose file (remove passwords!)
- Error logs: docker compose logs > logs.txt
- Steps to reproduce
Include system info:
```
uname -a
free -h
df -h
docker info
```

Security tip: Never share passwords, JWT secrets, or sensitive data in public issues!

Troubleshooting

Installation Issues

ClamAV Container Won’t Start

Database Connection Failed

Port Already in Use

Frontend Build Not Found

Login & Authentication Issues

Can’t Login After Fresh Install

Cookies Not Working

2FA Code Not Working

Passkey Registration Fails

Upload Issues

Upload Fails Immediately

Upload Stalls at 99%

“Virus detected” Error (False Positive)

Upload Limit Reached

Download Issues

Download Button Does Nothing

ZIP Download Corrupted

Download Link Shows 410 Error

Email Issues

Test Email Fails

Emails Not Received

Email Shows Broken Images

Performance Issues

Slow Upload Speeds

Application Unresponsive

High CPU Usage

SSL/HTTPS Issues

Certificate Errors

Mixed Content Warnings

Database Issues

“Connection refused” Errors

Database Corruption

Diagnostic Commands

View All Logs

Check Container Health

Inspect Container

Check Database Connection

Test Network Connectivity

Export Full Logs

Getting Help