Last Updated: 3/9/2026

Troubleshooting

This guide helps you diagnose and fix common issues with LinkAce. Follow these steps systematically before seeking help.

General Troubleshooting Steps

1. Enable Debug Mode

Debug mode provides more detailed error messages.

Add to .env:

APP_DEBUG=true

Restart (Docker):

docker compose restart app

Important: Disable debug mode in production after troubleshooting:

APP_DEBUG=false

2. Check System Logs

LinkAce logs errors and important events.

View logs in LinkAce:

• Username dropdown → System Logs

View log files directly:

• Docker: See Getting Logs from Docker
• Non-Docker: ./storage/logs/laravel-YYYY-MM-DD.log

3. Search the Community

Many issues have been solved before:

👉 GitHub Discussions

Search for your error message or symptoms.

4. Restart Everything

Sometimes a simple restart fixes the issue.

Docker:

docker compose restart

Non-Docker:

# Restart web server
sudo systemctl restart nginx  # or apache2
 
# Restart PHP-FPM (if applicable)
sudo systemctl restart php8.2-fpm

Server:

sudo reboot

Getting Logs from Docker

Access the Container

Find container name:

docker ps

Look for the LinkAce container (usually linkace-app-1 or similar).

Access the container:

# Single container
docker exec -it linkace-app-1 ash
 
# Docker Compose
docker compose exec app ash

View Log Files

Inside the container:

# Navigate to logs
cd /app/storage/logs
 
# List log files
ls -l
 
# View the latest log
cat laravel-$(date +%Y-%m-%d).log
 
# View last 50 lines
tail -n 50 laravel-$(date +%Y-%m-%d).log
 
# Follow logs in real-time
tail -f laravel-$(date +%Y-%m-%d).log

View Docker container logs:

# View all logs
docker compose logs
 
# View app logs only
docker compose logs app
 
# Follow logs in real-time
docker compose logs -f app
 
# Last 100 lines
docker compose logs --tail=100 app

Common Issues

Permission Errors

Permission issues are the most common problem.

.env File Not Writable

Symptom: Setup fails, can’t save configuration

Solution:

# Make writable
chmod 666 .env
 
# After setup, make read-only
chmod 644 .env

Docker note: Permissions apply outside the container too.

Storage Directory Not Writable

Symptom: Errors about cache, sessions, or logs

Solution:

Docker:

docker compose exec app chmod -R 0766 ./storage

Non-Docker:

cd /path/to/linkace
chmod -R 0766 ./storage

SQLite Database Not Writable

Symptom: Database errors with SQLite

Solution:

# Make database file writable
chmod 0766 database.sqlite
 
# Make directory writable (SQLite requirement)
chmod 0766 database/

Database Connection Errors

Password Mismatch

Symptom: “Access denied for user” or “could not connect to server”

Cause: Database password in .env doesn’t match the actual database password

Solution:

1. Verify passwords match in .env and docker-compose.yml
2. Check for special characters: If your password contains ?\/\$'", surround it with quotes:

   DB_PASSWORD="my$superSecret'DBPassword'"

3. Reset database (Docker, CAUTION: deletes all data):

   docker compose down
   docker volume ls  # Find the database volume
   docker volume rm linkace_linkace-db  # Replace with your volume name
   docker compose up -d

The default password in LinkAce is ChangeThisToASecurePassword!

Database Not Reachable

Symptom: “Connection refused” or “could not connect”

Solution:

1. Check database is running:

   docker compose ps

   All services should show “Up”.

2. Check database logs:

   docker compose logs db

3. Verify connection settings in .env:

   DB_CONNECTION=mysql
   DB_HOST=db  # For Docker Compose
   DB_PORT=3306
   DB_DATABASE=linkace
   DB_USERNAME=linkace
   DB_PASSWORD=YourPassword

4. Test database connection:

   docker compose exec db mysql -u linkace -p

   Enter the password from .env.

Docker Issues

Container Won’t Start

Symptom: Container exits immediately or won’t start

Solution:

1. Check logs:

   docker compose logs -f app

2. Check .env permissions:

   chmod 666 .env

3. Check Docker version:

   docker --version  # Should be 19+
   docker compose version  # Should support compose v3

4. Remove old containers and volumes:

   docker compose down -v
   docker compose up -d

Port Already in Use

Symptom: “Bind for 0.0.0.0:80 failed: port is already allocated”

Solution:

1. Find what’s using the port:

   sudo lsof -i :80

2. Change the port in docker-compose.yml:

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

3. Access LinkAce at http://localhost:8080

Image Not Found

Symptom: “manifest for linkace/linkace:latest not found”

Solution:

1. Try GitHub Container Registry:

   image: ghcr.io/kovah/linkace:latest

2. Check internet connection

3. Pull manually:

   docker pull linkace/linkace:latest

Setup Issues

Setup Wizard Not Loading

Symptom: Blank page or errors when accessing LinkAce

Solution:

1. Check .env file exists:

   ls -la .env

   If missing, copy from .env.example.

2. Generate app key:

   # Docker
   docker compose exec app php artisan key:generate
    
   # Non-Docker
   php artisan key:generate

3. Check web server is pointing to /public directory

4. Check logs for errors

Database Configuration Fails

Symptom: Setup wizard can’t connect to database

Solution:

1. Use command-line setup instead:

   # Docker
   docker compose exec app php artisan migrate
   docker compose exec app php artisan setup:complete
   docker compose exec app php artisan registeruser --admin
    
   # Non-Docker
   php artisan migrate
   php artisan setup:complete
   php artisan registeruser --admin

2. Verify database credentials in .env

Cron Not Working

Symptom: Links not archived, health checks not running, backups not happening

Solution:

1. Verify cron is configured:

   crontab -l

   Should show your LinkAce cron entry.

2. Test cron URL manually:

   curl https://your-linkace.com/cron/YOUR_TOKEN

   Should return “OK”.

3. Check System Logs for cron execution entries

4. Check server cron logs:

   # Ubuntu/Debian
   sudo tail -f /var/log/syslog | grep CRON
    
   # CentOS/RHEL
   sudo tail -f /var/log/cron

5. Regenerate cron token:

   • System Settings → Cron → Generate Token
   • Update your crontab with the new URL

See Post-Installation → Configure Cron for detailed setup.

Email Not Sending

Symptom: No emails received (invitations, password resets, notifications)

Solution:

1. Test email configuration:

   # Docker
   docker compose exec app php artisan mail:check
    
   # Non-Docker
   php artisan mail:check

   Enter an email address and check your inbox.

2. Verify SMTP settings in .env:

   MAIL_MAILER=smtp
   MAIL_HOST=smtp.example.com
   MAIL_PORT=587
   MAIL_USERNAME=your-username
   MAIL_PASSWORD=your-password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS="[email protected]"
   MAIL_FROM_NAME="LinkAce"

3. Check for common issues:

   • Wrong port: Try 587 (TLS) or 465 (SSL)
   • Wrong encryption: Try tls, ssl, or leave empty
   • ISP blocking: Some ISPs block SMTP ports
   • Gmail: Use an App Password , not your account password

4. Check logs for email errors:

   docker compose logs -f app | grep mail

5. Try a different provider: Test with a free SMTP service like Mailgun  or SendGrid 

See Post-Installation → Configure Email for detailed setup.

Link Issues

Title/Description Not Auto-Generating

Symptom: New links don’t have titles or descriptions

Solution:

1. Check the URL is accessible: Some sites block automated requests
2. Check cron is running: Auto-generation happens in background
3. Set manually: Edit the link and add title/description yourself
4. Check logs for errors when fetching metadata

Links Not Archiving to Wayback Machine

Symptom: No Wayback Machine link on link details page

Solution:

1. Wait: Archiving can take hours
2. Check cron is running: Archiving happens in background
3. Check robots.txt: Some sites block the Wayback Machine
4. Check System Settings: Ensure Wayback archiving is enabled
5. Check logs for archiving errors

Health Checks Not Running

Symptom: Link status always shows “OK” even for broken links

Solution:

1. Check cron is configured: See Cron Not Working
2. Check System Settings: Ensure link checks are enabled
3. Check frequency: May take days depending on your setting
4. Check logs for check errors

Search Issues

Search Not Working

Symptom: Search returns no results or errors

Solution:

1. Clear cache:

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

2. Check database connection

3. Check logs for search errors

Search Results Incomplete

Symptom: Some links don’t appear in search

Solution:

1. Check visibility: Private links only appear for the owner
2. Check tags/lists: Filters may be excluding results
3. Try different search terms: Search is case-insensitive but exact-match

SSO Issues

SSO Button Not Showing

Symptom: Login page doesn’t show SSO provider button

Solution:

1. Check .env configuration:

   SSO_ENABLED=true
   SSO_GOOGLE_ENABLED=true  # Or your provider

2. Restart:

   docker compose restart app

3. Clear cache:

   docker compose exec app php artisan config:clear

“Invalid Redirect URI” Error

Symptom: SSO provider shows redirect URI error

Solution:

1. Check redirect URI in your SSO provider matches exactly:

   https://your-linkace.com/auth/sso/[provider]/callback

   • No trailing slashes
   • HTTPS required (unless testing locally)
   • Replace [provider] with actual provider name (e.g., google, github)

2. Check your LinkAce URL is correct in .env:

   APP_URL=https://your-linkace.com

User Not Logging In

Symptom: SSO authentication succeeds but user isn’t logged in

Solution:

1. Check System Logs for SSO errors
2. Verify email is returned by the provider
3. Check SSO_REGISTRATION_ENABLED: If false, user must exist first
4. Create user manually: User Management → Invite User

See Single Sign-On → Troubleshooting for more SSO-specific help.

Backup Issues

Backups Not Running

Symptom: No backups in S3 storage

Solution:

1. Check cron is running: See Cron Not Working
2. Check S3 credentials in .env:

   BACKUP_ENABLED=true
   AWS_ACCESS_KEY_ID=your-key
   AWS_SECRET_ACCESS_KEY=your-secret
   AWS_BUCKET=your-bucket

3. Test manually:

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

4. Check logs for backup errors

Backup Fails with S3 Error

Symptom: “Access Denied” or “Bucket not found”

Solution:

1. Verify S3 credentials are correct
2. Check bucket permissions: Ensure write access
3. Check bucket region matches .env:

   AWS_DEFAULT_REGION=us-east-1

4. For non-AWS S3: Set endpoint:

   AWS_ENDPOINT=https://s3.example.com

See Application Backups for detailed setup.

Performance Issues

LinkAce is Slow

Solution:

1. Check server resources:

   # CPU and memory usage
   top
    
   # Disk space
   df -h

2. Check database size:

   # Docker
   docker compose exec db mysql -u linkace -p -e "SELECT table_schema AS 'Database', ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS 'Size (MB)' FROM information_schema.tables WHERE table_schema = 'linkace' GROUP BY table_schema;"

3. Clear old logs:

   # Docker
   docker compose exec app rm -f storage/logs/laravel-*.log
    
   # Non-Docker
   rm -f storage/logs/laravel-*.log

4. Optimize database:

   # Docker
   docker compose exec app php artisan optimize
    
   # Non-Docker
   php artisan optimize

5. Increase server resources: More RAM, faster CPU, SSD storage

High Database Load

Solution:

1. Reduce link check frequency: System Settings → every 14 or 30 days
2. Disable checks for problematic links: Link details → Disable Check
3. Optimize database:

   # MySQL
   docker compose exec db mysqlcheck -u linkace -p --optimize --all-databases

Getting Help

If you’ve followed this guide and still have issues:

1. Gather Information

System details:

# Server OS and version
uname -a
 
# Docker version
docker --version
docker compose version
 
# LinkAce version
# Check System Settings → Update Checks
 
# Container details (Docker)
docker container inspect linkace-app-1

Logs:

• System Logs from LinkAce
• Docker logs: docker compose logs --tail=100 app
• Server logs: /var/log/syslog or /var/log/messages

Configuration (sanitize passwords!):

• Relevant .env settings
• docker-compose.yml (if Docker)

2. Post to GitHub Discussions

👉 GitHub Discussions

Include:

• Clear description of the problem
• What you’ve tried from this guide
• System information (see above)
• Relevant logs (use Pastebin  for long logs)
• Steps to reproduce (if applicable)

Don’t post:

• Passwords or secrets
• “It doesn’t work” without details
• Duplicate threads (search first)

3. Paid Support

For dedicated, personalized support, consider becoming a supporter:

• Open Collective 
• Patreon 
• GitHub Sponsors 

Additional Resources

• Post-Installation Guide
• Installation with Docker
• Upgrading LinkAce
• CLI Commands
• Environment Variables
• GitHub Discussions 
• GitHub Issues