# Pterodactyl / Pelican

#### It is best to first review the vendor documentation

This documentation will likely be more up-to-date than mine

{% embed url="<https://pelican.dev/docs/troubleshooting/>" %}

{% embed url="<https://pterodactyl.io/panel/1.0/troubleshooting.html>" %}

***

{% hint style="info" %}
This section contains things that I've had to fix on my instance - it may not be helpful for you, but it may be a starting point too.
{% endhint %}

## Can't join Game Server/s

This section is to assist with troubleshooting port forwards, firewall rules and DDNS issues.

*This guide is assuming you're hosting the server in your home network, not on a cloud host.*

There are multiple areas where this can go wrong. Let's narrow it down, please refer to the below image.

<img src="/files/9eNG8WafUmJuVzVJkCus" alt="This network map assumes you are hosting your server in the same house / network as your personal PC. You may have additional devices, like network switches, WiFi etc. Generally, these devices won&#x27;t cause the issue you&#x27;re seeing, but they may." class="gitbook-drawing">

The above network map should be relatively similar to your home network. We have 4 devices,

1. Wings Node, where the game server is hosted
2. Your gaming PC
3. A Firewall / Modem / Router
4. friend's computer

**Our end goal is for the purple line (friends computer > firewall > pterodactyl node) to work.**

There are a few places that this line can fail,

1. Connecting to the Domain (DNS issue) or IP address
2. Bad port forwarding config in the modem / router
3. Bad firewall config in the Pterodactyl node
4. Bad game server installation config
5. ISP blocking the port or port forwarding completely
6. Your ISP uses CGNAT

#### 3 is the easiest to confirm;

To do this, we'll follow the orange line in the network map above

1. Get the LAN IP address for your Wings node. This is likely to start with 192.x.x.x, 10.x.x.x or 172.x.x.x
2. Connect to your game server via the internal IP:port, eg `192.168.1.20:25565`

{% tabs %}
{% tab title="I can join the server" %}
Most likely your port forward or (IF you are using a domain) your Domains DNS is bad.

have your friend connect via your [public IP address](https://whatismyipaddress.com/) and server port, eg `1.2.3.4:25565`

**If your friends are connecting via IP, skip this step.** Browse to [this website](https://whatismyipaddress.com/) to get your public IP address and [ping your domain](https://www.youtube.com/watch?v=TWZMVM_7csE). If the IP does not match, the DNS is incorrect. If so, you most likely have a dynamic DNS address - refer to [Broken mention](broken://pages/C1lBibws0V7rHjJ1gM2e) for a solution. Alternatively, your ISP may provide a static IP address at an additional cost.

If connecting directly to your public IP fails, confirm your port forward rule applies to the

* correct local IP
* correct port

**If it still fails to connect:**

**your ISP may be blocking port forwards.** I would suggest doing some Googling on your router / modem model to confirm your port forward rule has the correct syntax as some modems are awkward. You may have luck searching for `my modem model port forward minecraft server` but if you have no luck, you will need to ring your ISP.

**Your ISP may be using CGNAT.** You will need to contact your ISP to have this resolved. I would recommend watching <https://www.youtube.com/watch?v=eIpR5ZBCF_g>. Port forwarding will NEVER work behind a CGNAT without additional and complex network infrastructure.

Extra: You can use [this website](https://www.yougetsignal.com/tools/open-ports/) to test if a port is open (waiting for connections). Minecraft is a great server to test for this, as there are plenty of tools for testing things, [like this](https://mcsrvstat.us/)
{% endtab %}

{% tab title="Unable to join the server" %}
Firstly, lets confirm things are OK by

* Ping your server and confirm it responds
* Reboot your server

If all of the above is ok / has been done;

1. SSH onto your Pterodactyl node
2. Disable the firewall\
   If you are using Ubuntu, the command is listed below\
   `sudo UFW disable`
3. Attempt to connect to the server via the internal IP:port

If it works, you will need to allow the port/s through the Firewall rule. [Please refer back to the documentation, this step is already outlined](/guides/installation-guides/pterodactyl/creating-a-new-wings-node.md#allow-ports-through-the-firewall). You may have missed additional steps as well.

If this does not work,

* the game server is not running
* you are looking at the wrong server or
* you are looking at the wrong port

Refer back to Pterodactyl Panel and check if the server is running and on what ports
{% endtab %}
{% endtabs %}

### Troubleshooting Dynamic DNS

{% hint style="info" %}
You can skip troubleshooting DDNS by trying to connect to your game server via your [public IP](https://whatismyipaddress.com/) instead
{% endhint %}

1. Navigate to <https://whatismyipaddress.com/> and take note of your IP address
2. Launch `CMD` or the shell of your choice
3. Type `ping YOUR.DDNS.ADDRESS.HERE` and hit enter\
   eg `ping play.reallycoolservers.com`
4. Take note of the output and refer to the below table

{% tabs %}
{% tab title="Successful Ping" %}

<pre data-overflow="wrap"><code>C:\Users\you>ping play.reallycoolservers.com

Pinging play.reallycoolservers.com [123.123.123.123] with 32 bytes of data: 
Reply from 123.123.123.123: bytes=32 time&#x3C;1ms TTL=64 
Reply from 123.123.123.123: bytes=32 time&#x3C;1ms TTL=64 
Reply from 123.123.123.123: bytes=32 time&#x3C;1ms TTL=64 
Reply from 123.123.123.123: bytes=32 time&#x3C;1ms TTL=64

Ping statistics for 123.123.123.123: <a data-footnote-ref href="#user-content-fn-1">Packets: Sent = 4, Received = 4</a>, Lost = 0 (0% loss), Approximate round trip times in milli-seconds: Minimum = 0ms, Maximum = 0ms, Average = 0ms
</code></pre>

**A server has responded to your pings, great!**

1. Confirm that the IP address matches your Google result
   * If it matches, great! Skip to
   * If it doesn't match, there is an issue with your DDNS container. Review the logs for the container

**Your DDNS config is correct**
{% endtab %}

{% tab title="Could not find host" %}

<pre><code>C:\Users\you>ping play.reallycoolservers.com

<a data-footnote-ref href="#user-content-fn-2">Ping request could not find host play.reallycoolservers.com</a>. Please check the name and try again.
</code></pre>

{% hint style="warning" %}
**This needs to be resolved before you can continue any further**
{% endhint %}

Firstly, review your ping command and ensure the address is correct. If the address is correct you have one of the following issues

* The DDNS container is failing to update your IP - refer to its logs
* You have not waited enough time for DNS to update - this can take up to a few hours
* If you've made a typo in the address, redo the test with the correct address

{% hint style="info" %}
If you've confirmed all of the above is correct, give it some time. Sometimes DNS takes a long time to propagate across the internet.
{% endhint %}
{% endtab %}

{% tab title="Resolves IP but fails to connect" %}

<pre data-overflow="wrap"><code>C:\Users\you>ping play.reallycoolservers.com

Pinging play.reallycoolservers.com [123.123.123.123] with 32 bytes of data:
Request timed out.
Request timed out.
Request timed out.
Request timed out.

Ping statistics for 123.123.123.123:
    <a data-footnote-ref href="#user-content-fn-3">Packets: Sent = 4, Received = 0, Lost = 4 (100% loss),</a>
</code></pre>

**You have resolved an IP address but the server does not respond to pings**

Confirm that the resolved IP address matches your [public IP](https://whatismyipaddress.com/)

* If the IP address matches, great! - Some firewalls / routers are configured to NOT respond to pings as a security measure. **You can continue to the next step**
* If the IP address does not match, there is something wrong with your DDNS container. Review the logs for the container
  {% endtab %}
  {% endtabs %}

***

## Panel Errors

### Error 500

Yeah its broken! Post on the Pterodactyl / Pelican discord for assistance.

### The MAC key is invalid

Your APP\_KEY in the panel .env file has changed. You will need to restore the .env file, or wipe nad rebuild Pelican / Ptero from scratch. You will need to recreate your servers and move files over etc.

If you don't have the key, try the Pelican / Pterodactyl Discord for support before starting again

### mountedActionsData.0.files

Your proxy addresses are not correct. Refer to [Broken mention](broken://pages/J4ZVZc4q9GDkhaJqnBPs#configure-proxy-address)

## Wings Errors

### Token ID error

[Broken mention](broken://pages/xWnrCiJYVBIEFMum3PLH#if-the-health-is-still-red-try)

If you are using a reverse proxy, it may be stripping the authentication headers.

### FATAL: failed to configure docker environment error=Error response from daemon: Pool overlaps with other one on this address space

Wings has defaulted to a docker network range that is in-use. The easiest way to resolve this is to edit your config.yml file, per step [Creating a Wings node](/guides/installation-guides/pterodactyl/creating-a-new-wings-node.md#upload-configuration-file-to-wings)to include the below lines

```yaml
docker:
  network:
    interfaces:
      v4:
        subnet: 172.31.0.0/24
        gateway: 172.31.0.1
```

### Panel is unable to see Node

1. Start the Wings container if its not running
2. Check your docker logs, you should see something similar to below

   <figure><img src="/files/5dne2plLosh5rmXRroh2" alt=""><figcaption></figcaption></figure>
3. Open your internet browser and navigate to hostname:port, you should see the below error;

   <pre><code><strong>{"error":"The required authorization heads were not present in the request."}
   </strong></code></pre>
4. Navigate to your admin panel > nodes
5. Right click anywhere and select Inspect
6. Click on the console tab
7. Review the errors

If you have a `token_id` error, it may be a bad config file.

If you have a `... is not Pelican Wings` error, restarting the node, panel and walk away for 15 minutes

If you have an error with `cloudflareaccess.com` in the url, such as below - your Application bypass policy isn't working. Stop your stack, delete the dockflare volume and start it again. Wait 5 minutes and check again

```console
https://xxx.cloudflareaccess.com/cdn-cgi/access/login/wings.agame…-XzXCXRPPH9zspmqCwhpw7i83VTWfHcc6ne8PFfW5SEGA&redirect_url=%2Fapi%2Fsystem does not match node token_id !
[Alpine] console.error("https://xxx.cloudflareaccess.com/cdn-cgi/access/login/wings.xxx.com?kid=xxx
```

### Pool overlaps with other one on this address space

{% code title="Wings container logs" overflow="wrap" %}

```log
failed to configure docker environment error=Error response from daemon: Pool overlaps with other one on this address space
Stacktrace: Error response from daemon: Pool overlaps with other one on this address space
```

{% endcode %}

#### Symptoms

* Servers wont start but containers are running
* Wings node shows as offline in Panel
* Unable to navigate to Wings proxy url
* Error above in logs for Wings container

This one is pretty easy to solve and can be done proactively (straight after installing Wings)

Wings, by default, chooses docker network 172.18.0.0 for its game servers. This is a low range and it only takes pushing 18 stacks to run into this issue.

[Per Pterodactyl's doco](https://discord.com/channels/122900397965705216/493443725012500490/838633961911091201), the best way to work around this is changing the subnet that Wings uses in the Wings config file. To do so,

1. Log into Portainer and access your Wings node
2. On the left, click on Stacks
3. Click on your Wings stack
4. Scroll down to containers and open the 'Wings' container (not DB)
5. Scroll down and note the volume mapped to /etc/pterodactyl
6. On the left, select Volumes
7. Click on 'browse' next to the volume noted in step 4
8. Download the config file
9. Open it in your editor of choice
10. Locate the 'Docker' section and take note of the highlighted information below

    <figure><img src="/files/LIudZ8mhLmnI6hOSrqi1" alt=""><figcaption><p>Red = interface IP<br>Yellow - Subnet range<br>Green - Gateway IP</p></figcaption></figure>
11. Go back to Portainer and select the 'Networks tab
12. Confirm that your v4 subnet (orange) is used by another stack
13. Update the 3 fields to be a range that is not in use
    * Red and Green field will be the same and must be in the same subnet range as orange (eg 172.172.0.1)
    * Orange must be a valid subnet range, with the last 2 digits as 0 (eg 172.172.***0.0/16***)\
      \&#xNAN;*Aka only change the second IP number ( 123.**123**.123.123 )*
14. Upload the config file back into the relevant volume
15. Restart the Wings stack

#### Please note:

The example provided above (172.172.0.0/16) clashes with public IP's. You may experience issues with these containers accessing the internet using this subnet. [Please refer to this doco for a list of private subnets](https://www.arin.net/reference/research/statistics/address_filters/)

I'm personally running 172.172.0.0/16 and haven't encountered issues, as this only affects the docker Wings and game server containers, but your mileage may vary.

## Database issues

### Create a new database - An unexpected error was encountered while processing this request. please try again

Have you set the HASHID variable per [Creating a Panel](/guides/installation-guides/pterodactyl/creating-a-new-panel.md) documentation?

If not, please re-read the documentation as you may have missed other steps too...

### Game is unable to connect to server database

Try connecting via IP. This may be a docker DNS issue.

[^1]: sent 4, recieved 4. The connection is good

[^2]: Could not find host. DDNS config is bad

[^3]: Sent 4, recieved 0. Fail


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.trentbauer.com/guides/troubleshooting/pterodactyl-pelican.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.