Add troubleshooting section for "MAC invalid" errors during backup restoration

[Cinzya]

Summary

Users who restore Coolify backups to new servers frequently encounter "MAC invalid" errors when trying to access encrypted configurations (S3 settings, server configurations, SSH keys, etc.). While the current documentation mentions using APP_PREVIOUS_KEYS, it doesn't explicitly address this specific error message, making it difficult for users to understand the connection.

Problem Description

When users restore a Coolify backup without properly preserving the original APP_KEY, they experience:

• Successful login to the dashboard
• "MAC invalid" or "The MAC is invalid" errors when accessing any encrypted configuration
• Inability to view or modify S3 settings, server configurations, or SSH keys
• Can create new resources but cannot access previously configured ones
• Resources may only be accessible via direct links
• Complete loss of access to encrypted data from the old instance

Current Documentation Gap

The existing backup restore documentation at /docs/knowledge-base/how-to/backup-restore-coolify.md mentions:

• The importance of saving the APP_KEY
• Adding APP_PREVIOUS_KEYS to the .env file
• A generic "500 Error on Login or Project Access" troubleshooting item

However, it doesn't:

• Specifically mention the "MAC invalid" error, which is the actual error message users see
• Explain that APP_PREVIOUS_KEYS supports multiple keys (critical for complex migration scenarios)

Proposed Addition

Add a new troubleshooting item to the existing troubleshooting section:

- **"MAC invalid" or "The MAC is invalid" Errors When Accessing Configurations:**
  This error occurs when Coolify cannot decrypt data that was encrypted with a different application key. This commonly happens after restoring a backup if the original `APP_KEY` wasn't properly preserved.
  
  **Symptoms:**
  - Can log into Coolify dashboard successfully
  - Get "MAC invalid" errors when accessing S3 storage, servers, or SSH keys
  - Can create new resources but cannot access old ones
  - Existing resources may only work via direct links
  
  **Solution:**
  1. Ensure you have the original `APP_KEY` from your old Coolify instance
  2. Add it to your new server's `.env` file as `APP_PREVIOUS_KEYS`:
     ```yaml
     APP_PREVIOUS_KEYS=base64:your_old_app_key_here
     ```
     
     **Important:** If you have migrated or restored multiple times, you may have multiple previous keys. The `APP_PREVIOUS_KEYS` variable supports multiple keys separated by commas:
     ```yaml
     APP_PREVIOUS_KEYS=base64:first_old_key,base64:second_old_key,base64:third_old_key
     ```
     Add ALL previous keys that may have been used to encrypt your data.
     
  3. Re-run the Coolify installation script to apply the changes:
     ```sh
     curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash -s <version>
     ```
  
  **Prevention:**
  Always backup your `.env` file separately when creating backups. The `APP_KEY` is essential for decrypting your data and cannot be recovered if lost. If you perform multiple migrations, keep track of all `APP_KEY` values used.
  
  **If you lost your APP_KEY:**
  Unfortunately, encrypted data cannot be recovered without the original key. You will need to:
  - Create new environments and manually recreate your services
  - Reconfigure all S3 storage settings
  - Re-add all server configurations

Benefits

• Users will immediately recognize the error they're experiencing
• Clear connection between the error message and the solution
• Explains the multiple keys feature that users are often unaware of
• Comprehensive symptoms list helps with troubleshooting
• Emphasis on prevention to avoid future issues
• Clear guidance for worst-case scenario (lost key)
• Reduces support burden from repeated questions about this error

Related Issues

• [Bug]: MAC is invalid after backup restore coolify#3761 - Original issue discussing this problem with detailed explanation
• [Bug]: The MAC is invalid. coolify#6505 - Issue where user was unaware that APP_PREVIOUS_KEYS supports multiple keys
• Multiple Discord and community forum discussions about "MAC invalid" errors

Additional Context

The "MAC invalid" error is a Laravel-specific error message that occurs when the Message Authentication Code (used for verifying encrypted data integrity) fails validation. This happens when data encrypted with one key is attempted to be decrypted with a different key.

Key finding from issue #6505: Users are often unaware that APP_PREVIOUS_KEYS can contain multiple comma-separated keys, which is essential for scenarios where Coolify has been migrated or restored multiple times with different keys.

This is a critical issue that affects many users during migration/restoration, and having clear documentation would significantly improve the user experience.

---

Would love to see this added to help users who encounter this common issue during backup restoration!