v0.6.0

Runtime Issues

Common problems encountered during PteroCA operation and how to resolve them.

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/cache

This 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.

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.log for production, or var/log/dev.log if 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 .env file in the PteroCA directory and set APP_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 switch APP_ENV back to prod in the .env file 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 .env file and verify that the DATABASE_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 .env should 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 (or dev.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:

This 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:

After 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.

Related Documentation

PreviousInstallation IssuesNextCommon Errors

Last updated