v0.6.0

Installation Issues

Common problems encountered during PteroCA installation and initial setup.

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:

# Recommended (v0.6+)
php bin/console pteroca:user:create email securePassword ROLE_ADMIN

# Deprecated (still works until v1.0.0)
# php bin/console app:create-new-user email securePassword ROLE_ADMIN

This 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 pteroca:user:change-password command in a similar way (old name: app:change-user-password).

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 pteroca:system:configure) 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."

then the issue is not always related to the allowed_origins configuration. While missing origins is the most common cause, there are other factors that can prevent WebSocket connections from working correctly.

Expand to see the complete list of the most frequent causes

1. Missing allowed_origins entry (Pterodactyl restriction)

By default, Pterodactyl Wings only allows WebSocket connections from localhost. If your PteroCA panel is hosted on a different domain or IP, the console request is blocked.

Solution: Edit /etc/pterodactyl/config.yml and add your panel domain or IP:

Restart Wings afterward.

2. Reverse proxy not forwarding WebSockets

If Wings is behind NGINX, Apache, Traefik or any reverse proxy, it must explicitly forward WebSocket headers. Missing headers cause the console to connect → immediately close → reconnect in a loop.

Ensure the reverse proxy includes:

3. Cloudflare Proxy (orange cloud) blocking WebSockets

If your Wings domain/IP is behind Cloudflare with proxy enabled, Cloudflare may terminate or reject WebSocket connections.

Fix: Turn the DNS entry gray (DNS only).

4. Firewall or blocked port

The browser connects directly to Wings on its configured port (default: 8080). If port 8080 is blocked by a firewall or hosting provider, WebSocket connections fail.

Ensure 8080/tcp is open.

5. HTTPS/SSL Mismatch

Browsers block insecure WebSocket connections if the panel uses HTTPS but Wings uses HTTP.

Both must be either:

  • HTTPS (recommended), or

  • HTTP (not recommended)

For more details, see the Configure Allowed Origins section in the Pterodactyl Integration documentation.

Product Unavailable

If a product appears in the catalog but cannot be purchased, and the store displays:

"The product is currently unavailable."

the most common causes are related to product configuration or node capacity limits.

Expand to see the complete list of reasons why a product may be marked as unavailable

1. Node does not have enough available resources

Even if a product is configured correctly, the assigned node must have enough free:

  • RAM

  • CPU

  • Disk space

  • Allocations

  • Remaining server slots (if configured)

If the node cannot deploy another server, the system disables the product to avoid failed purchases.

2. Node, Nest, or Egg is inactive or misconfigured

The product will become unavailable if:

  • The node is offline,

  • The nest or egg was deleted or changed,

  • API connection to Pterodactyl failed.

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:

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.

Solution

Solution Option 1 – Temporarily Disable IPv6:

This disables IPv6 until the next reboot, allowing apt to use IPv4.

Solution Option 2 – Prefer IPv4 Over IPv6: Edit the /etc/gai.conf file and uncomment the following line:

This prioritizes IPv4 when both IPv4 and IPv6 addresses are available. After saving the file, run:

to retry the package installation.

Once either method is applied, MariaDB packages should install without 404 errors. For more details on setting up MariaDB, see the MariaDB Official Repository Guide.

Related Documentation

PreviousTroubleshootingNextRuntime Issues

Last updated