> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poplock.scyne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common issues

> Fixes for the most frequently encountered problems with PopLock Server.

<AccordionGroup>
  <Accordion title="Server fails to start">
    Check the error log for the cause, then verify permissions and the startup script.

    ```bash theme={null}
    cat /tmp/minecraft_error.log
    ```

    ```bash theme={null}
    serv status
    ```

    If the process failed due to a permissions problem, restore ownership of the server directory:

    ```bash theme={null}
    sudo chown -R $USER:$USER /usr/local/games/minecraft_server/java
    ```

    Verify that `start.sh` is executable:

    ```bash theme={null}
    ls -l /usr/local/games/minecraft_server/java/start.sh
    ```
  </Accordion>

  <Accordion title="Snapshot didn't run">
    Confirm the cron entry exists, then check whether it fired and what the last run produced.

    Verify the cron entry:

    ```bash theme={null}
    sudo crontab -l
    ```

    Check the last run output:

    ```bash theme={null}
    tail -50 /var/log/minecraft_snapshot.log
    ```

    Verify cron fired at the expected time:

    ```bash theme={null}
    grep CRON /var/log/syslog | tail -20
    ```
  </Accordion>

  <Accordion title="Datapack function not found (Unknown function poplock:alert)">
    The pack format number in `pack.mcmeta` does not match the running server version.

    <Steps>
      <Step title="Get the correct pack format number">
        Run the following command in the server console to identify the current version:

        ```
        version
        ```
      </Step>

      <Step title="Rebuild the datapack">
        Update `pack.mcmeta` with the matching pack format number for your Minecraft version.
      </Step>

      <Step title="Re-download the datapack">
        Replace the existing datapack file on the server with the rebuilt version.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="tmux socket permission error">
    Reset the permissions on the tmux socket file:

    ```bash theme={null}
    sudo chmod 770 /tmp/minecraft-tmux
    sudo chown $USER:$USER /tmp/minecraft-tmux
    ```
  </Accordion>

  <Accordion title="Server won't stop gracefully during snapshot">
    The snapshot script automatically force-kills the server after 30 seconds if it does not stop on its own. No manual action is needed for a one-off occurrence.

    <Note>
      If force-kills happen regularly, check available system memory. The server may be thrashing under load during the snapshot window.
    </Note>
  </Accordion>

  <Accordion title="A Minecraft server is already running (but it's not)">
    This is caused by a zombie tmux session that outlived the server process.

    `serv start` automatically detects and cleans up zombie sessions before starting. If you need to remove the session manually:

    ```bash theme={null}
    tmux -S /tmp/minecraft-tmux kill-session -t minecraft
    ```
  </Accordion>

  <Accordion title="Player count unavailable on serv status">
    The player count display requires the `mcstatus` Python package. Install it with:

    ```bash theme={null}
    pip install mcstatus
    ```

    Once installed, `serv status` will show the current player count automatically.
  </Accordion>
</AccordionGroup>