Last Updated: 3/10/2026

Troubleshooting Common Issues

This guide helps you diagnose and resolve common LinkAce problems. Find your issue below and follow the solutions.

Quick Diagnostics

Before diving into specific issues, gather basic diagnostic information:

System Information

Docker installations:


# Check container status
docker compose ps
 
# View application logs
docker compose logs -f app
 
# View all logs
docker compose logs -f
 
# Check Docker version
docker --version
docker compose version
 
# System info
docker system info

Non-Docker installations:


# Check PHP version
php -v
 
# Check web server status
sudo systemctl status nginx
# or
sudo systemctl status apache2
 
# Check application logs
tail -f storage/logs/laravel.log
 
# Check web server logs
sudo tail -f /var/log/nginx/error.log

Container/Environment Details

Docker:


# View docker-compose.yml
cat docker-compose.yml
 
# View environment
docker exec linkace-app-1 env
 
# Inspect container
docker container inspect linkace-app-1

Non-Docker:


# View .env file
cat .env
 
# Check file permissions
ls -la storage/
ls -la bootstrap/cache/

Installation Issues

Setup Wizard Won’t Load

Symptoms:

Blank page at http://localhost
“Connection refused” error
404 Not Found

Solutions:

Verify containers are running (Docker):
```
docker compose ps
```
All containers should show “Up” status.

Check port availability:


# Check if port 80 is in use
sudo lsof -i :80
# or
sudo netstat -tulpn | grep :80

If port 80 is taken, use a different port in docker-compose.yml:


ports:
  - "8080:80"  # Use port 8080 instead

Check application logs:
```
docker compose logs app
```
Look for error messages.

Verify .env file:


cat .env | grep APP_KEY

Should show a key like base64:.... If empty:


docker exec linkace-app-1 php artisan key:generate

Check firewall:
```
# Allow port 80
sudo ufw allow 80/tcp
```

Database Connection Failed

Symptoms:

“Could not connect to database”
“SQLSTATE[HY000] [2002] Connection refused”

Solutions:

Wait for database to start (Docker):
```
# Database takes 30-60 seconds to initialize
docker compose logs db
```
Wait for “ready for connections” message.

Verify database credentials in .env:


DB_CONNECTION=mysql
DB_HOST=db          # For Docker, use 'db' not 'localhost'
DB_PORT=3306
DB_DATABASE=linkace
DB_USERNAME=linkace
DB_PASSWORD=YourPasswordHere

Test database connection (Docker):
```
docker exec linkace-db-1 mysql -u linkace -p linkace
```
Enter password from .env. Should connect successfully.

Check database container:


docker compose ps db
docker compose logs db

Recreate database container:


docker compose down
docker volume rm linkace_linkace_db  # Destroys data!
docker compose up -d

⚠️ Warning: This deletes all data. Only for fresh installations.

Permission Errors

Symptoms:

“Permission denied” errors
“Unable to write to storage”
Setup fails at file creation

Solutions:

Docker installations:

Permission issues are rare in Docker. If they occur:


# Fix storage permissions
docker exec linkace-app-1 chown -R www-data:www-data /app/storage
docker exec linkace-app-1 chmod -R 0766 /app/storage

Non-Docker installations:

Fix storage permissions:


cd /path/to/linkace
chmod -R 0766 storage/
chmod -R 0766 bootstrap/cache/

Set correct owner:


# For nginx
sudo chown -R www-data:www-data storage/
sudo chown -R www-data:www-data bootstrap/cache/
 
# For Apache
sudo chown -R apache:apache storage/
sudo chown -R apache:apache bootstrap/cache/

Check SELinux (RHEL/CentOS):


sudo setenforce 0  # Temporary disable
# If this fixes it, configure SELinux properly

Can’t Log In

Symptoms:

“Invalid credentials” error
Login form redirects back
“Too many login attempts”

Solutions:

Reset password via command line:


# Docker
docker exec -it linkace-app-1 php artisan linkace:reset-password
 
# Non-Docker
php artisan linkace:reset-password

Follow prompts to reset password.

Check user exists:


# Docker
docker exec linkace-app-1 php artisan linkace:list-users
 
# Non-Docker
php artisan linkace:list-users

Clear rate limiting (too many attempts):


# Docker
docker exec linkace-app-1 php artisan cache:clear
 
# Non-Docker
php artisan cache:clear

Wait 15 minutes or clear rate limit cache.

Check session configuration:


SESSION_DRIVER=file
SESSION_LIFETIME=10080

Two-Factor Authentication Issues

Symptoms:

Lost access to 2FA device
2FA codes don’t work
Can’t disable 2FA

Solutions:

Use recovery code:
- At login, click “Use recovery code”
- Enter one of your saved recovery codes
- After login, regenerate recovery codes or disable 2FA

Disable 2FA via command line (admin):


# Docker
docker exec -it linkace-app-1 php artisan linkace:disable-2fa user@example.com
 
# Non-Docker
php artisan linkace:disable-2fa user@example.com

Check time synchronization:
- 2FA codes are time-based
- Ensure server time is correct:
```
date
```
- Ensure phone time is correct
- Time difference > 30 seconds causes failures

Session Expires Too Quickly

Symptoms:

Logged out after a few minutes
“Session expired” messages

Solutions:

Increase session lifetime in .env:


SESSION_LIFETIME=10080  # 7 days in minutes

Clear cache and restart:


# Docker
docker exec linkace-app-1 php artisan config:clear
docker compose restart
 
# Non-Docker
php artisan config:clear

Check session driver:


SESSION_DRIVER=file  # or 'redis' if Redis is configured

Performance Issues

Slow Page Loading

Symptoms:

Pages take 5+ seconds to load
Timeouts
Unresponsive interface

Solutions:

Enable Redis caching:

Docker (already included in docker-compose.yml):


CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=redis
REDIS_PASSWORD=YourRedisPassword
REDIS_PORT=6379

Reduce entries per page:
- User Settings → “Number of entries in lists”
- Set to 25 or lower

Clear caches:


# Docker
docker exec linkace-app-1 php artisan cache:clear
docker exec linkace-app-1 php artisan view:clear
docker exec linkace-app-1 php artisan config:clear
 
# Non-Docker
php artisan cache:clear
php artisan view:clear
php artisan config:clear

Check database size:


# Docker MySQL
docker exec linkace-db-1 mysql -u linkace -p -e "SELECT table_name, ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)' FROM information_schema.TABLES WHERE table_schema = 'linkace' ORDER BY (data_length + index_length) DESC;"

Large tables (>1GB) may need optimization.

Increase PHP memory limit:
```
# Add to .env
PHP_MEMORY_LIMIT=256M
```

High Memory Usage

Symptoms:

Out of memory errors
Container restarts
Server crashes

Solutions:

Increase Docker memory limit:

Edit docker-compose.yml:


services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M

Reduce queue workers:


QUEUE_CONNECTION=sync  # Process jobs synchronously

Archive old links:
- Move old links to “Archive” list
- Delete broken links
- Clean up duplicates

Feature Issues

Cron Jobs Not Running

Symptoms:

Link checks not happening
Backups not running
Wayback Machine not archiving

Solutions:

Verify cron is configured:
- Go to System Settings
- Check “System Cron” section
- Should show “Last run: X seconds ago”

Check crontab:


crontab -l

Should show LinkAce cron entry:


* * * * * curl -s https://your-linkace-url/cron/YOUR-TOKEN

Test cron URL manually:
```
curl https://your-linkace-url/cron/YOUR-TOKEN
```
Should return “OK” or “Cron executed”.

Check cron logs:


# View system cron logs
sudo tail -f /var/log/syslog | grep CRON

Alternative: Docker exec method:


# Edit crontab
crontab -e
 
# Add:
* * * * * docker exec linkace-app-1 php artisan schedule:run >> /dev/null 2>&1

For complete setup, see Post-Installation Setup.

Metadata Not Fetching

Symptoms:

Title and description stay blank
No preview image
“Failed to fetch metadata” error

Solutions:

Check URL is accessible:
```
curl -I https://example.com
```
Should return 200 OK.

Increase timeout:


META_GENERATION_TIMEOUT=20  # Default is 10

Check User-Agent: Some sites block automated requests:


APP_USER_AGENT="Mozilla/5.0 (compatible; LinkAce/2.0)"

Verify site allows scraping:
- Some sites require authentication
- Some block scraping (robots.txt)
- Some use JavaScript-only content

Test manually:


# Docker
docker exec linkace-app-1 php artisan linkace:fetch-metadata https://example.com
 
# Non-Docker
php artisan linkace:fetch-metadata https://example.com

Bookmarklet Not Working

Symptoms:

Clicking bookmarklet does nothing
Popup blocked
“Undefined” error

Solutions:

Check popup blocker:
- Allow popups for your LinkAce domain
- Check browser extension settings
Reinstall bookmarklet:
- Go to User Settings
- Drag bookmarklet button to bookmarks bar again
Clear browser cache:
- Clear cache and cookies
- Restart browser
- Try bookmarklet again
Check HTTPS:
- Bookmarklet may not work on HTTP sites if LinkAce is HTTPS
- Mixed content security policy
Try different browser:
- Test in Chrome, Firefox, or Safari
- Check browser console for errors (F12)

Wayback Machine Not Archiving

Symptoms:

Links not sent to Internet Archive
No archive links shown

Solutions:

Enable in User Settings:
- User Settings → “Wayback Machine backups”
- Enable “Backup links to the Wayback Machine”
Verify cron is running:
- System Settings → “System Cron”
- Must show recent run
Check site allows archiving:
- Some sites block Wayback Machine (robots.txt)
- Login-required pages won’t archive
Manual archive:
- Visit: https://web.archive.org/save/YOUR-URL
- Manually trigger archiving

Link Monitoring Not Working

Symptoms:

Link status never updates
All links show “Unknown” status

Solutions:

Verify cron is running:
- Check System Settings → “System Cron”

Manual link check:


# Docker
docker exec linkace-app-1 php artisan links:check
 
# Non-Docker
php artisan links:check

Check specific link:
- Open link details page
- Click “Check Now” button
- View result and error message
Review check history:
- Link details page → “Check History”
- See past check results and errors

Backup & Restore Issues

Backups Not Running

Symptoms:

No backup files created
Backup directory empty

Solutions:

Verify backup is enabled:


grep BACKUP_ENABLED .env
# Should show: BACKUP_ENABLED=true

Check cron is running:
- System Settings → “System Cron”

Check permissions:


# Docker
docker exec linkace-app-1 ls -la /app/storage/app/backups
 
# Non-Docker
ls -la storage/app/backups

Directory must be writable.

Manual backup:


# Docker
docker exec linkace-app-1 php artisan backup:run
 
# Non-Docker
php artisan backup:run

Check for error messages.

For complete backup guide, see Backup & Restore.

Restore Failed

Symptoms:

Database restore errors
Missing data after restore

Solutions:

Check database version:
- Use same MySQL/PostgreSQL version as backup source
- Restore from MySQL 8.0 to MySQL 5.7 may fail

Empty database first:


# Docker MySQL
docker exec linkace-db-1 mysql -u root -p -e "DROP DATABASE linkace; CREATE DATABASE linkace;"

Check backup file integrity:
```
unzip -t backup-file.zip
```
Review error messages:
- SQL syntax errors → version mismatch
- Permission errors → user access issues

Email Issues

Emails Not Sending

Symptoms:

No notification emails
Password reset emails not received

Solutions:

Verify email configuration:
```
grep MAIL_ .env
```

Test email:


# Docker
docker exec linkace-app-1 php artisan linkace:test-email your@email.com
 
# Non-Docker
php artisan linkace:test-email your@email.com

Check spam folder

Verify SMTP credentials:


MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls

Check SMTP connection:
```
telnet smtp.example.com 587
```

Review logs:


# Docker
docker compose logs app | grep mail
 
# Non-Docker
tail -f storage/logs/laravel.log | grep mail

For complete email setup, see Email Configuration.

Upgrade Issues

Upgrade Failed

Symptoms:

Errors after upgrading
White screen
Database errors

Solutions:

Run migrations:


# Docker
docker exec linkace-app-1 php artisan migrate --force
 
# Non-Docker
php artisan migrate --force

Clear all caches:


# Docker
docker exec linkace-app-1 php artisan cache:clear
docker exec linkace-app-1 php artisan config:clear
docker exec linkace-app-1 php artisan view:clear
docker exec linkace-app-1 php artisan settings:clear-cache
 
# Non-Docker
php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan settings:clear-cache

Check version compatibility:
- Verify PHP version meets requirements
- Check database version
Review upgrade guide:
- See Upgrading LinkAce
- Check version-specific upgrade notes

Getting Help

If you’re still stuck:

1. Gather Information

Collect this information before asking for help:


# LinkAce version
cat docker-compose.yml | grep image
# or
php artisan --version
 
# PHP version
php -v
 
# Docker version (if applicable)
docker --version
docker compose version
 
# Recent logs
docker compose logs --tail=100 app
# or
tail -100 storage/logs/laravel.log

2. Community Support

GitHub Discussions - Ask questions, share solutions
GitHub Issues - Report bugs (check existing issues first)

3. Premium Support

Get dedicated support by becoming a supporter:

Next Steps

Essential Reading

Installation Guide - Proper installation
Post-Installation Setup - Essential configuration
Upgrading LinkAce - Update procedures

Advanced Topics

CLI Commands - Command-line tools
Environment Variables - Configuration reference
Backup & Restore - Data protection

Most issues can be resolved with proper configuration and maintenance! 🔧

Troubleshooting Common Issues

Quick Diagnostics

System Information

Container/Environment Details

Installation Issues

Setup Wizard Won’t Load

Database Connection Failed

Permission Errors

Login & Authentication Issues

Can’t Log In

Two-Factor Authentication Issues

Session Expires Too Quickly

Performance Issues

Slow Page Loading

High Memory Usage

Feature Issues

Cron Jobs Not Running

Metadata Not Fetching

Bookmarklet Not Working

Wayback Machine Not Archiving

Link Monitoring Not Working

Backup & Restore Issues

Backups Not Running

Restore Failed

Email Issues

Emails Not Sending

Upgrade Issues

Upgrade Failed

Getting Help

1. Gather Information

2. Community Support

3. Premium Support

Next Steps

Essential Reading

Advanced Topics