Skip to content

FAQ

Jump to bottom Edit New page
AlexProgrammerDE edited this page Dec 29, 2025 · 5 revisions

FAQ & Troubleshooting

Common Issues

"Server not set up" Error

Error messages like:

  • Main Server "main" not set up!!!
  • Queue Server "queue" not set up!!!
  • Auth Server "auth" not set up!!!

Cause: Your proxy config is missing the servers that PistonQueue expects.

Solution: Add the required servers to your proxy configuration.

BungeeCord Example 
servers:
  main:
    motd: '&1Main Server'
    address: 127.0.0.1:25566
    restricted: false
  queue:
    motd: '&1Queue Server'
    address: 127.0.0.1:25567
    restricted: false
Velocity Example 
[servers]
main = "127.0.0.1:25566"
queue = "127.0.0.1:25567"

Make sure the server names in PistonQueue's config match exactly (case-sensitive).

Players Not Moving Through Queue

Possible causes:

  1. Target server is down - Check pauseQueueIfTargetDown setting
  2. Target server is full - Check reserved slots configuration
  3. No players in queue - Use /pq stats to verify
  4. Queue move delay too high - Check queueMoveDelay setting

Debugging steps:

  1. Run /pq stats to see queue sizes
  2. Run /pq slotstats to see slot usage
  3. Check proxy console for errors
  4. Verify target server is running and accessible

Queue Position Not Showing

Check these settings:

positionMessageChat: true      # Shows in chat
positionMessageHotBar: false   # Shows above hotbar
positionPlayerList: true       # Shows in tab list

At least one should be true.

Players Bypassing the Queue

Possible causes:

  1. Player has bypass permission - Check for queue.bypass
  2. Player is OP on proxy - OPs may have all permissions
  3. alwaysQueue is false - Players skip queue when server isn't full
  4. Wrong source server - If using lobbies, check enableSourceServer

Shadow Bans Not Working

Check:

  1. Player name is spelled correctly (case-sensitive for some auth systems)
  2. Ban duration format is correct (e.g., 2d, 12h, 30m)
  3. shadowBanType is set to your preferred mode

Test with:

/pq shadowban TestPlayer 1m

Frequently Asked Questions

Can I have multiple target servers?

Yes! Use queue groups to route different queues to different servers:

queueGroups:
  survival:
    targetServers:
      - "survival"
    queueTypes:
      - "REGULAR"
      - "PRIORITY"
  creative:
    targetServers:
      - "creative"
    queueTypes:
      - "CREATIVE_QUEUE"

Can I use this for a hub/lobby server?

PistonQueue is designed for a linear flow (queue -> target). For complex hub networks, you'll need to configure it carefully:

  1. Set enableSourceServer: true
  2. Set sourceServer: "lobby"
  3. Configure your lobby to send players to the queue server when they want to join the target

How do reserved slots work?

Reserved slots ensure each queue type has guaranteed space on the target server.

Example:

  • Server max: 100 players
  • VETERAN slots: 20
  • PRIORITY slots: 30
  • REGULAR slots: 50

This means:

  • 20 slots are guaranteed for veterans
  • 30 slots are guaranteed for priority players
  • 50 slots are for regular players

If there are no veterans online, their slots can be used by others, but veterans will always have priority when joining.

Can players play games while in queue?

Technically possible but not recommended. PistonQueue is designed for minimal resource usage with players locked in place. Making a "playable queue" causes:

  • Increased server load
  • Potential exploits
  • More complex configuration
  • No official support

How do I update the plugin?

  1. Download the latest version
  2. Stop your proxy and queue server
  3. Replace the old JAR with the new one
  4. Start your servers
  5. Check for config migration messages

The plugin handles config migrations automatically when possible.

Does it work with Geyser/Floodgate?

Yes, PistonQueue works with Bedrock players through Geyser. No special configuration is needed.

How do I show queue stats in my MOTD?

Use PistonMOTD with these placeholders:

  • %pistonqueue_regular% - Regular queue size
  • %pistonqueue_priority% - Priority queue size
  • %pistonqueue_veteran% - Veteran queue size

(Queue type names are lowercase in placeholders)

Can I customize the queue position message?

Yes, edit queuePosition in the config:

queuePosition: "&6Position in queue: &l%position%"

Available placeholders:

  • %position% - Queue position
  • %wait% - Estimated wait time
  • %server_name% - Server name

Getting Help

If you can't find an answer here:

  1. Check the GitHub Issues
  2. Join our Discord Server
  3. Include these details when asking for help:
    • PistonQueue version (/pq version)
    • Proxy type and version (BungeeCord/Velocity)
    • Relevant config sections
    • Error messages from console
    • Steps to reproduce the issue

Discord | GitHub | Modrinth

PistonQueue

Getting Started

Help

Links

Clone this wiki locally