Common Issues
Find the right Aquadactyl or Manta troubleshooting steps before contacting support.
Start with the symptom you can see, check the matching component, and make one change at a time. Most checks in these guides inspect the current state; repairs are explained separately.
If you use someone else's panel, start with the browser checks and collect the error for your panel administrator. Host commands are for the operator of that installation.
Find your issue
| What you see | Start here |
|---|---|
| Panel shows a 500 error, 502, or a blank page | Panel errors and logs |
| Login loops, 419 errors, or settings redirect to HTTP | HTTPS, proxies and cookies |
| Installer fails, PHP is too old, or database login is denied | Installation and database checks |
Update rejects names such as |mcmods in the Blueprint audit | Select the fixed Installer |
| Blueprint reapplication rejects external paths and leaves maintenance enabled | Recover the interrupted update |
| Schedules, emails or queued jobs do not run | Queues and scheduler |
| An extension fails, or the interface looks outdated | Blueprint and frontend assets |
| The Egg Library says every egg is no longer available | Egg Library API update |
| Passkeys, OAuth or two-factor authentication fail | Account access |
| Manta stops with the page-number HTTP 422 error | Known pagination startup error |
Clone fails, manta is missing, or its service cannot be found | Checkout and service recovery |
| Servers show unavailable, or console and quick actions fail | Panel, browser and node connectivity |
| Manta cannot connect to Docker, or a port is already in use | Docker and listeners |
| Files appear missing, SFTP fails, or uploads are rejected | Files and SFTP, upload limits |
| A game exits with code 137, or a Mac cannot access server files | Server exits, macOS mounts |
For an addon page with a missing API route, see addon backend installation. For Manta displaying Wings release notes, see daemon update products.
First checks
- Record the exact error, action and time, including your timezone. Reproduce once so you can find the matching log entry.
- Check the scope: one account, one server, one node, or the whole panel. A working panel page does not establish that the browser can reach a node.
- Check the installed versions against current releases. Panel, Manta and Installer versions are separate. An installer version argument does not update an older checkout of the installer itself.
- Note what changed immediately before the problem: update, extension, domain, proxy, credentials, storage path or service configuration.
- Follow the matching guide and retry after a specific correction. Keep a backup before changing configuration or running an update.
Preserve the panel's application key, database, node configuration and server volumes. Deleting them, regenerating an existing application key, making files world-writable, or bypassing certificate checks can cause data loss or expose the installation. They are not general troubleshooting steps.
Collect useful evidence
Use a short excerpt around the failure, rather than an entire log directory.
Panel log previews and Manta diagnostics are described in the component guides.
Keep APP_DEBUG=false on a public panel, even when temporarily collecting debug
logs.
Review evidence before sharing it. Remove passwords, application keys, node/API
tokens, OAuth client secrets, Discord webhook URLs, session cookies and bearer
credentials. Browser network exports and WebSocket URLs can contain tokens too.
Automatic redaction still needs a human review. Never attach a complete .env
or node config.yml to a public report.
If the relevant checks do not resolve it, use this template for your administrator or a report in the Panel or Manta repository:
Component and installed version:
Deployment: native Linux / Docker / Dokploy / macOS
Host OS and architecture, if relevant:
Scope: one user / one server / one node / all users
Action and exact error or HTTP status:
Time and timezone:
Steps to reproduce:
Expected result and actual result:
Recent changes:
Checks performed and their results:
Relevant, reviewed and redacted log excerpt:Suspected compromise, exposed credentials, or potential data corruption should be escalated privately. Preserve logs and backups before further changes.