Bug Reports & Contributing

Block-Suite is actively developed. If you find a bug, experience unexpected behavior, or have a feature request, please report it on GitHub so it can be addressed promptly.

How to Report a Bug

Bug Report Template

Copy and paste this into your GitHub issue body:

## Bug Report

**Block-Suite Version:** (e.g. v1.0.0 — check title bar)
**OS:** (e.g. Windows 11 23H2)
**Java Version:** (run `java -version`)

### What happened?
<Describe the bug clearly. What did you expect vs. what actually happened?>

### Steps to Reproduce
1. Open Block-Suite
2. Go to [tab name]
3. Set [these options]
4. Click [button]
5. ==> Bug occurs

### Error Messages / Logs
<Paste any error text from the Activity Log, console, or Velocity logs.
If none, write "No errors shown.">

```
Paste log output here
```

### Screenshots
<Attach screenshots that show the issue. Use drag-and-drop on GitHub.>

### Settings
- Target IP/Port: 
- Forwarding Mode: 
- Online Mode: 
- ViaVersion: 
- Theme: 

### Additional Context
<Any other relevant details: target server type, network setup, etc.>

Where to Find Logs

Log Source	Location	What It Contains
Activity Log	Server Cloning tab → bottom panel	All proxy events, connection attempts, player data, errors. Copy or open in separate window.
Velocity Console	runtime/velocity/logs/latest.log	Full Velocity proxy logs — startup, connection details, stack traces.
Java Console	Run Block-Suite from terminal: java -jar blocksuite.jar	JavaFX exceptions, unhandled errors, startup failures.
Playit.gg Logs	runtime/playit/	Tunnel connection status, errors, claim URLs.

Common Issues & Solutions

Velocity won't start

• Ensure Java 17+ is installed and in your system PATH
• Check if another process is using port 25577 (default Velocity bind port)
• Look for errors in runtime/velocity/logs/latest.log
• Click Setup Environment again to regenerate configs

Players can't connect / get disconnected

• Verify the target server is online using the Status button
• Check the forwarding mode — try none first, then legacy if needed
• If using playit.gg, ensure the tunnel is active and the claim URL was completed
• Try disabling HAProxy Protocol if players drop immediately on connect
• Enable ViaVersion if the client version doesn't match the target

Server status shows "Offline" but the server is running

• Double-check the IP address and port in Server Cloning tab
• The target may have a firewall blocking status pings — try with a known public server first
• Some servers use SRV records; try the numeric IP directly

Playit.gg tunnel not working

• The first time you start a tunnel, a claim URL appears in the Activity Log — you must open it in a browser and claim the tunnel
• Check if runtime/playit/playit.exe was downloaded successfully
• Ensure no firewall is blocking outgoing connections to playit.gg

Update check fails / "Copy Error" appears

• Block-Suite checks https://api.github.com for new releases
• Ensure you have internet connectivity
• If the error persists, click Copy Error to copy the technical details and include them in your bug report

"Port already in use" error

• A previous Velocity instance may still be running. Open Task Manager and end any java.exe processes.
• Another application may be using port 25577. Change the port in Velocity's config or stop the other app.

Feature Requests

Have an idea for a new feature? Open a GitHub issue with the enhancement label:

## Feature Request

### What would you like?
<Describe the feature clearly.>

### Why is it useful?
<Explain the use case or problem it solves.>

### Possible implementation
<Optional: suggest how it could work.>

Security & Responsible Use

If you discover a security vulnerability in Block-Suite itself, please report it privately via GitHub's Security Advisory feature rather than opening a public issue.

Quick Links