Troubleshooting
If you encounter issues with PteroCA, gathering and reviewing error logs is often the first step to diagnosing the problem. Below are some common troubleshooting techniques to help you identify and resolve issues in your Symfony project.
Installation and Initial Setup Issues
Unable to Log In After Installation
If you cannot log in to the PteroCA panel after a fresh installation, it usually indicates that the integration with the Pterodactyl panel was not set up properly, and the user account was not created or is not accessible. The most frequent cause is that the PteroCA Pterodactyl Addon (plugin) was not installed on your Pterodactyl instance. This plugin is essential for PteroCA to communicate with Pterodactyl (for example, it enables creating client API keys via the API). Without it, certain requests from PteroCA to Pterodactyl will fail.
Solution: Ensure that you have installed the PteroCA addon on your Pterodactyl panel before or immediately after installing PteroCA. Follow the official instructions to install the plugin (via Composer) on your Pterodactyl panel. After installing the plugin, you may need to create an admin user for PteroCA manually if the initial user was not created. You can do this using PteroCA’s CLI command for user creation. For example, run:
php bin/console app:create-new-user email securePassword ROLE_ADMINThis command will create a new admin user in PteroCA (and also create the user in Pterodactyl if the API connection is configured). Use the email and password you specify to log in. If you already have an initial user but forgot the password, you can reset it with the app:change-user-password command in a similar way.
Pterodactyl API Integration Errors
During installation, PteroCA needs to communicate with the Pterodactyl panel to create accounts and other resources. If something is misconfigured, you may encounter errors. Below are common error messages and how to fix them:
Error while connecting to the Pterodactyl API: This means PteroCA could not reach the Pterodactyl panel via the API. Ensure that the Pterodactyl URL is correct and reachable, and that the API key is correct. During installation, you must provide a Pterodactyl Application API Key (not a Client API Key) with proper permissions. Double-check that the URL (including port and protocol) and the API key are configured correctly. If needed, you can update these settings by re-running the configuration command (
php bin/console app:configure-system) or by editing your environment variables.“This action is unauthorized”: This error indicates the API key used does not have sufficient permissions to perform the requested action on the Pterodactyl panel. You should create a new Application API Key in Pterodactyl’s admin interface, making sure to grant all the required read/write permissions (for example, users, servers, etc.). Update PteroCA with this new key (you can use the configuration command mentioned above to update the API credentials). Using a client key or a key with limited scope will cause this issue, so ensure it’s an Application key with full permissions.
“The resource you are looking for could not be found”: This typically means that the Pterodactyl panel cannot find an API endpoint that PteroCA is calling. The most likely reason is that the PteroCA plugin is not installed on the Pterodactyl panel. PteroCA might be trying to perform an action (such as creating a client API key for a user) that isn’t supported by a standard Pterodactyl installation. Install the PteroCA Pterodactyl Addon plugin on your panel to resolve this. After installing the plugin, try the operation again. (For reference, see the [PteroCA Pterodactyl Addon documentation]for why this plugin is needed.)
Console Connection Issues
A common post-installation issue occurs when trying to open the server console in the panel, resulting in an error such as:
“An error occurred while connecting to the console. The console connection has been closed.”
This happens because Pterodactyl’s security settings restrict WebSocket connections to only allowed origins. By default, Pterodactyl (Wings) allows connections from localhost only. If your PteroCA panel runs on a different domain or IP, the request is blocked.
Solution: Edit the Pterodactyl Wings configuration file /etc/pterodactyl/config.yml and add your PteroCA panel domain or IP to the allowed_origins section. You may also use a wildcard (*) to allow all origins, though this is not recommended in production.
Example:
allowed_origins:
- '127.0.0.1' # Replace with your domain or IP where PteroCA is hosted
- '*' # Optional: allow any origin (less secure)Save the file and restart the Wings service if required. Once updated, the console should connect successfully. For more details, see the Configure Allowed Origins section in the PteroCA Basic Configuration Guide.
Auto-Installer Issues
MariaDB Repository Installation Error
Another common issue during installation is failing to fetch MariaDB packages due to IPv6-only connectivity. The error may look like this:
404 Not Found [IP: 2606:4700::6811:bf0e 443]This typically happens when the server has IPv6 enabled but either no IPv4 connectivity or misconfigured IPv6 routing, and the MariaDB mirror doesn’t respond correctly over IPv6.
Permission Denied Errors
If you encounter errors related to file permissions (for example, errors saying a file in var/log or var/cache cannot be written), it’s likely that your web server user (e.g., www-data on Ubuntu/Debian) does not have the correct permissions to write to those directories. This often happens after installation or an update, when file ownership or modes have changed.
Solution: Adjust the ownership and permissions of the relevant directories so that the web server can write to them. For example, you can run the following commands in your PteroCA installation directory to fix permissions:
sudo chown -R www-data:www-data var/log var/cache
sudo chmod -R 775 var/log var/cacheThis will ensure the var/log and var/cache directories are owned by the web server user and group, and are writable (permission 775 allows write access to the owner and group).
After running these commands, try accessing the panel or performing the action again to see if the error is resolved.
Commons Issues and Solutions
500 Internal Server Errors
A generic “500 Internal Server Error” in the browser can occur for many reasons – such as a misconfigured server environment, a PHP error, or an uncaught exception in the application. Here’s how to troubleshoot a 500 error in PteroCA:
Check the logs: Inspect the log files (
var/log/prod.logfor production, orvar/log/dev.logif in development mode) for any fatal errors or exceptions around the time the error occurred. The logs often contain detailed stack traces or messages pointing to the cause (e.g. a missing configuration, a database error, etc.). This is the first place to look for clues.Check file permissions: If the logs are empty or not updating when the 500 error occurs, it might be due to the application not being able to write to the log files. Ensure that the folder permissions are set correctly (see Permission Denied Errors above) so that logs can be written and the application can function properly.
Enable debug mode for details: If the cause is not obvious, temporarily switch the app to development mode to get a detailed error page. Open the
.envfile in the PteroCA directory and setAPP_ENV=dev, then refresh the page that was showing the 500 error. In development mode, Symfony will display a detailed error trace in the browser, which can help identify the problem. Once you have the information you need, remember to switchAPP_ENVback toprodin the.envfile after fixing the issue, to disable debug output and restore normal operation (leaving the app in dev mode in production is not recommended for security and performance reasons).
If you cannot determine the cause of the 500 error or the issue seems complex, consider seeking help:
You can open an issue on the GitHub repository with a description of the problem and any relevant log output.
You can ask for support in the PteroCA Discord community by opening a support ticket.
Providing the error details and any steps to reproduce will help others assist you more effectively.
Database Connection Issues
If PteroCA is unable to connect to your database, you may see errors during installation or in the logs (for example, exceptions about database connections or credentials). This is usually due to incorrect database configuration. To troubleshoot database connection issues:
Verify configuration: Open your
.envfile and verify that theDATABASE_URL(or the relevant DB host, name, user, password fields) are correct. Ensure the hostname/IP, port, database name, username, and password are all set to the correct values for your database server. For example, a typical MySQL connection string in.envshould look like:DATABASE_URL=mysql://db_user:[email protected]:3306/db_name(with your own credentials in place).Check the logs: Look at
var/log/prod.log(ordev.log) for any database-related error messages. Common issues include authentication failures (wrong username/password), network/time-out errors (if the database host is unreachable), or missing database driver extensions. The log message will often indicate what went wrong (e.g., “SQLSTATE[HY000] [1045] Access denied for user” indicates a credentials issue).
If you find a misconfiguration, update the .env or configuration files accordingly and then clear the cache or restart the application if necessary. After fixing the details, the application should be able to connect to the database.
Missing or Outdated Dependencies
If the panel is behaving oddly, or you encounter errors like classes not found or undefined functions, it might be due to missing or outdated PHP dependencies. This can happen if Composer didn’t install everything correctly, or if you pulled a new version of PteroCA and haven’t updated the vendor libraries.
Solution: Run Composer to install or update dependencies. From the root of your PteroCA installation, execute:
composer installThis will install any dependencies not already present. If you want to update existing packages to their latest allowed versions (as specified in composer.json), you can run:
composer updateAfter running these, ensure that the vendor/ directory contains all the required libraries and try loading the panel again. Keeping dependencies up-to-date (and installed) will prevent a lot of runtime errors.
Twig Template Errors
Twig template errors occur when there is an issue in the front-end templates (Twig is the templating engine PteroCA uses for rendering pages). These issues can be caused by syntax errors in Twig files or missing variables that the template expects.
If you encounter a blank page or an error page related to rendering, check the logs for a message about a Twig error. The log will usually indicate the file name and line number in the Twig template where the error occurred, as well as a description (for example, “Unexpected token” or “Variable XYZ does not exist”).
Solution: Once you identify the problematic template and error from the logs, correct the issue in the Twig file. This might involve fixing the syntax (for example, correcting an unclosed tag or a typo in a variable name) or adjusting the logic in the template. If the error was due to a missing variable, you may need to ensure that the controller or context providing data to the template includes that variable. After making changes, clear the application cache (if caching is enabled) and reload the page to see if the issue is resolved.
By being attentive to template error messages and fixing the indicated problems, you can quickly restore normal page rendering.
Accessing Error Logs
PteroCA (being a Symfony application) logs errors and important events to log files located in the var/log/ directory. These logs are extremely useful for debugging because they often contain detailed error messages and stack traces that are not visible in the browser.
Here are some tips for working with log files:
Viewing Recent Logs
To see the latest errors or messages, you can view the end of the log file. Using a terminal on the server, run a command like the following to show the last 100 lines of the production log:
tail -n 100 var/log/prod.logIf your application is in development mode or you want to check development logs, use the dev.log file instead:
tail -n 100 var/log/dev.logThis will output the most recent entries in the log, which may include error stack traces, warnings, or other relevant information. Scanning this output can give you immediate clues about what is going wrong.
Monitoring Logs in Real Time
If you are actively troubleshooting an issue, it can be useful to watch the logs as the application runs. You can “follow” the log file so that new entries are displayed live. For example:
tail -f var/log/prod.logThis will continuously print new log lines to your terminal as they are written. If you trigger an action in the app (like loading a page or performing an operation) that causes an error, you will see the corresponding log entry appear in real time. For development mode logs, do the same with dev.log:
tail -f var/log/dev.logPress Ctrl+C to stop the live log monitoring. Real-time log monitoring is very helpful when you need to reproduce an issue and see the error immediately as it happens.
Resetting Logs
Sometimes, especially during debugging, the log files can become long and cluttered with previous errors, which makes it hard to find new entries. You might want to clear the log file before reproducing an issue, so you can focus only on the fresh log output.
To empty (truncate) the production log, you can use:
> var/log/prod.logThis will wipe the contents of prod.log (note the single > which redirects nothing into the file, effectively clearing it). Do the same for dev.log if needed. After clearing the log, perform the steps to reproduce your issue and then check the logs again (via tail or by opening the file) – you will now see only the new log entries, which makes it easier to pinpoint the problem.
By keeping these troubleshooting tips in mind and consulting the error logs, you can resolve most common issues with PteroCA. If an issue persists or isn’t covered here, don’t hesitate to reach out to the community or maintainers with details of your problem. Good logging and clear error reports will greatly speed up the support process.
Last updated