Skip to Content
docsgeneralTroubleshooting

Last Updated: 3/9/2026

Troubleshooting Guide

If you have issues with LinkAce or run into errors, follow these steps before creating a discussion or issue on GitHub.

Disclaimer

LinkAce is built and shared without charge. The developer has spent significant free time building this application and won’t offer free personal support, customization, or installation help.

Need help? Visit the community forum and post your issue there.

Help Others Help You

When posting problems:

  • Help others understand your problem
  • Post details about your setup
  • Explain what you’ve tried
  • Describe what you expected

After following this guide, you’ll have much more information to share, helping others understand and fix your problem.

Golden rule: Be nice and patient.

Step 1: Enable Debug Mode

The very first step is enabling Debug Mode for more detailed error messages.

Add this to your .env file:

APP_DEBUG=true

Step 2: Get More Logs

Logs are information collected by various LinkAce components.

When LinkAce is Running

Find logs under System Logs in the menu.

When LinkAce is Not Running

Find logs in ./storage/logs.

Getting Logs from Docker

Container names vary depending on your setup. In a regular setup, the LinkAce container should be linkace-app-1.

Find your container name:

docker ps

Access the Container

Single Docker containers:

docker exec -it [your LinkAce container name] ash

Docker Compose:

docker compose exec -it app ash

View Logs Inside Container

# View all log files
cd /app/storage/logs
 
# Open the latest log file
cat laravel-2025-02-26.log

Step 3: Search the Community Forum

Search the community forum for your error message. Many issues are already solved.

Step 4: Restart LinkAce

As bland as it sounds, try restarting LinkAce. If that doesn’t help, restart your server.

Step 5: Post to the Forum

If you can’t solve the issue with detailed information or forum threads, post a new one.

Sharing Logs and Info

For large log files and additional info, use Pastebin  instead of posting thousands of lines directly in the thread.

Share Tech Stack Details

  • Proxy/Load Balancer: Share details and logs if necessary
  • Cloudflare or other provider: Mention if running in front of LinkAce
  • SSO provider: Share setup details and logs if applicable

Gather System Information

Note: Instructions are for Linux systems.

# General server details
uname -a
 
# Docker system details
docker system info
 
# LinkAce container setup
cat docker-compose.yml
docker container inspect [your LinkAce container name]

Common Issues

Permission Issues

The most common issue is permissions.

.env File Permissions

The .env file needs to be writable for setup. Change back to non-writable afterward.

Note: This applies outside the Docker container too, as permissions are shared!

# Make writable
chmod 0666 .env
 
# Make non-writable
chmod 0655 .env

Storage Directory Permissions

The storage directory contains:

  • Caches
  • Sessions
  • Logs
  • Application backups

Ensure folders are writable by the user running LinkAce. In the official Docker container, this is always www-data.

Inside Docker container:

docker exec -it [your LinkAce container name] chmod -R 0766 ./storage

General PHP setup:

cd [Path to your LinkAce folder]
chmod -R 0766 ./storage

SQLite Database Special Case

If running LinkAce with SQLite, ensure the folder containing the database is writable. This is an SQLite requirement.

Database Connection Issues

If you start the Docker setup and change the database password later, there will be a mismatch between the actual password and what LinkAce knows.

Note: No help is provided for changing passwords inside your database. Refer to your database server’s official documentation.

Special Characters in Password

If using special characters like ?\/$'" in your password:

  • Change to other characters, OR
  • Surround password with " quotes in .env:
DB_PASSWORD="my$superSecret'DBPassword'"

Starting from Scratch (No Setup Yet)

If you haven’t set up LinkAce yet, delete your database and start over.

⚠️ CAUTION: These steps assume the standard LinkAce Docker setup.

# Stop the setup
docker compose down
 
# Find the database volume (should end with `linkace-db`)
docker volume ls
 
# ====== !CAUTION! ======
# THIS REMOVES YOUR DATABASE VOLUME AND EVERYTHING INSIDE!
# VERIFY THE NAME IS CORRECT!
docker volume rm linkace_linkace-db
 
# Start LinkAce again
docker compose up -d

Default password: ChangeThisToASecurePassword!

User Api Tokens