Troubleshooting
Start with Admin → System health: it checks PHP, extensions, the database, folders, permissions, .htaccess, URL rewriting, cron, configuration, the base URL, short domains and security settings, and explains each warning. Error details are written to Admin → System logs and storage/logs.
Installation
| Problem | Solution |
|---|---|
| Blank page or 500 Internal Server Error | Check the PHP version is 8.1 or newer in MultiPHP Manager. Look in cPanel Errors for the message |
| URL rewriting is not working | .htaccess is missing (enable Show Hidden Files and upload it) or the host disallows .htaccess overrides |
| Extension missing | Enable it in Select PHP Version → Extensions |
| Folder not writable | Set folders to 755 in File Manager; ask your host if PHP does not run as your account |
| Database is not empty | Create a new empty database or remove the existing tables |
| Access denied for user | Check the user was added to the database with all privileges; use the full prefixed names (for example account_user) |
| Pages load without styling | Files were extracted into a subfolder; move them into public_html |
Links and redirects
| Problem | Solution |
|---|---|
| Every short link shows Not found | The alias does not exist on that domain, or the domain is not active |
| This alias is reserved | The word is used by the application; choose another alias |
| Destination not allowed | It points to a private address, to this service, or matches the blocklist |
| Clicks are not counted | HEAD requests, previews and bot visits are not counted as clicks |
| Location shows Unknown | Upload a GeoLite2 database in Admin → Settings → Analytics |
| Times look wrong | Set your time zone in Profile |
Custom domains
See the troubleshooting table in Custom domains. Most problems are a mistyped TXT record name, a domain whose document root is not the same public_html, or a missing SSL certificate.
Cron and webhooks
| Problem | Solution |
|---|---|
| Health says cron is not running | Check the command and PHP path in Cron Jobs; run it once in Terminal to see errors |
| Webhooks stay pending | Cron is not running, the webhook is disabled, or the endpoint keeps failing (see the delivery log) |
| Signature invalid in your app | Use the raw request body and the current secret; secrets change when rotated |
| Problem | Solution |
|---|---|
| No emails arrive | Use Send test email; check spam; use a sender address on your domain or switch to SMTP |
| SMTP authentication failed | Check username, password, port (465 SSL or 587 TLS) and encryption |
Sign-in
| Problem | Solution |
|---|---|
| Too many attempts | Wait for the lockout period (default 15 minutes), or sign in from a network you have used before |
| Page expired | The form was open too long or cookies are blocked; reload and try again |
| Locked out as the only super admin | Use Forgot password with your email. If email does not work, ask your host to run a password reset through phpMyAdmin |
API
Every error response contains a request_id. Administrators can find the matching request in the API request log. See the error codes in REST API.
Getting help
When reporting a problem, include the time it happened, the page or API endpoint, the request ID if shown, and the related entry from System logs. Never share config/config.php or backup files.