Skip to main content

​
Resource Pack Issues

​
Players Not Receiving Resource Pack

If players are not receiving the resource pack automatically, check your server configuration.
Possible causes:
  1. Resource pack hosting is not configured properly
  2. Server resource pack settings conflict with BetterHud
  3. Network/firewall blocking resource pack download
Solutions:
1

Check BetterHud configuration

Verify config.yml has proper resource pack hosting settings:
resource-pack:
  enabled: true
  auto-generate: true
2

Verify server.properties

Ensure your server.properties doesn’t have conflicting resource pack settings. BetterHud manages resource packs automatically.
3

Check firewall/network

If using external hosting, ensure the resource pack URL is accessible from player networks.

​
Resource Pack Download Fails

Error: “Failed to download resource pack”
This usually indicates a hosting or connectivity issue.
Solutions:
  • Verify the resource pack file isn’t corrupted by checking console logs
  • If using external hosting, test the URL in a web browser
  • Check file size limits - some hosts have restrictions
  • Ensure players have sufficient bandwidth

​
HUD Elements Not Showing

HUD configured but nothing appears in-game
1

Verify resource pack acceptance

Players must accept the resource pack when joining. Check if they declined it.
2

Check console for errors

Look for errors during resource pack generation:
tail -f logs/latest.log | grep BetterHud
3

Verify HUD is enabled

Check if the HUD is enabled for the player:
/betterhud turn on <player>
4

Check conditions

Verify any display conditions in your HUD configuration are met.

​
Configuration Errors

​
YAML Parsing Errors

Error: “Could not parse YAML file”
YAML is whitespace-sensitive. Incorrect indentation will cause parsing failures.
Common issues:
  • Mixed tabs and spaces (use spaces only)
  • Incorrect indentation levels
  • Missing colons after keys
  • Unescaped special characters in strings
Solution: Use a YAML validator to check your configuration:
  1. Copy your YAML content
  2. Paste into a validator like yamllint.com
  3. Fix any reported errors
  4. Reload BetterHud: /betterhud reload

​
Invalid Placeholder Syntax

HUD shows literal placeholder text instead of values 
# Wrong
pattern: "Health: health"

# Correct
pattern: "Health: [health]"
BetterHud uses [placeholder] syntax by default. PlaceholderAPI uses %placeholder%.

​
Missing Image/Font Files

Error: “Could not find image: filename.png” Solutions:
  1. Verify the file exists in the correct directory
  2. Check file name spelling and case (Linux is case-sensitive)
  3. Ensure file extension is included in configuration
  4. Check file permissions are readable

​
Compatibility Issues

​
Conflicts with Other Plugins

Certain plugins may conflict with BetterHud’s resource pack generation.
Known conflicts:
  • ItemsAdder - May conflict with resource pack merging
  • Oraxen 2.0 - Support dropped as of BetterHud 1.10, use Nexo instead
  • Custom resource pack plugins - May override BetterHud’s pack
Solutions:
  1. Check if the plugin supports resource pack merging
  2. Configure load order in your server startup
  3. For Nexo/CraftEngine: BetterHud 1.14+ auto-merges resource packs
  4. Disable conflicting plugin’s resource pack feature and use BetterHud’s API to add content

​
Version Compatibility Errors

Error: “Unsupported server version”
BetterHud supports specific Minecraft versions. Check compatibility before updating.
Supported versions:
  • Bukkit/Folia: 1.20.4 - 1.21.11
  • Velocity: 3.3 - 3.4
  • Fabric: 1.21.11
  • Client: 1.20.4+ (as of v1.14.1, ≤1.20.2 clients are not supported)
Solution: Either:
  • Update your server to a supported version
  • Or downgrade BetterHud to a version supporting your server version

​
Client-Side Mod Conflicts

Players using Optifine or Sodium report rendering issues
BetterHud does not officially support closed-source client mods like Optifine.
Some shaders and resource pack features in client mods may interfere with BetterHud. Players experiencing issues should:
  1. Try disabling shader packs
  2. Test without Optifine/problematic mods
  3. Report specific rendering issues with details

​
Performance Issues

​
Server Lag After Installing BetterHud

Server TPS drops after enabling BetterHud
1

Check resource pack generation

Initial resource pack generation can be intensive. Wait for it to complete and check if lag persists.
2

Review HUD complexity

Very complex HUDs with many elements/conditions can impact performance. Simplify HUD definitions.
3

Check update frequency

Reduce update tick rate in config if HUDs update too frequently:
update-period: 20 # Increase this value (in ticks)
4

Profile with timing reports

Use /timings (Paper) or similar profiling to identify bottlenecks.

​
High Memory Usage

BetterHud consuming too much memory Solutions:
  • Reduce number of cached resource pack files
  • Optimize image file sizes (use appropriate resolution)
  • Restart server periodically to clear caches
  • Allocate more RAM to your server if needed

​
Client FPS Drops

Players report FPS drops with BetterHud enabled
Since BetterHud renders on the client, complex HUDs can impact client performance.
Solutions:
  1. Reduce number of rendered elements
  2. Optimize image sizes and formats
  3. Reduce animation complexity
  4. Disable certain HUD elements for low-end clients
  5. Players should allocate more RAM to Minecraft client

​
Database Issues

​
Database Connection Errors

Error: “Could not connect to database” For MySQL users:
1

Verify credentials

Check database connection settings in config.yml:
database:
  type: mysql
  host: localhost
  port: 3306
  database: betterhud
  username: your_username
  password: your_password
2

Test connection

Verify you can connect to the database from your server using a MySQL client.
3

Check firewall

Ensure MySQL port (default 3306) is accessible from your server.
4

Verify user permissions

Database user needs CREATE, SELECT, INSERT, UPDATE, DELETE permissions.

​
Command Issues

​
Commands Not Working

Error: “Unknown command” when using /betterhud Solutions:
  1. Verify BetterHud loaded successfully in console logs
  2. Check for command conflicts with other plugins
  3. Ensure you have permission: betterhud.admin
  4. Try the full command: /hud instead of /betterhud

​
Permission Errors

Error: “You don’t have permission to use this command”
BetterHud uses a permission system. Ensure players/groups have appropriate permissions.
Common permissions:
  • betterhud.admin - Admin commands
  • betterhud.reload - Reload configuration
  • betterhud.use - Use HUD features
Add permissions via your permission plugin (LuckPerms, etc.).

​
Platform-Specific Issues

​
Fabric-Specific Issues

Required: Fabric API must be installed
BetterHud for Fabric requires Fabric API to be installed.
If you get “Missing dependency” errors:
  1. Download Fabric API for your Minecraft version
  2. Place it in your mods/ folder
  3. Restart the server

​
Velocity-Specific Issues

Players on different backend servers see different HUDs This is expected behavior. Configure BetterHud on each backend server individually, or use a shared database for synchronized player data.

​
Folia-Specific Issues

Threading errors on Folia
BetterHud is designed to work with Folia’s threading model. Ensure you’re using the latest version.
If experiencing threading issues:
  1. Update to latest BetterHud version (1.12+ has Folia fixes)
  2. Report the issue on GitHub with thread dump

​
Getting Additional Help

If your issue isn’t listed here:
  1. Check console logs for detailed error messages
  2. Join Discord for community support: discord.com/invite/rePyFESDbk
  3. Search GitHub Issues for similar problems: github.com/toxicity188/BetterHud/issues
  4. Report bugs with full details (see FAQ for what to include)
When asking for help, always include:
  • BetterHud version
  • Server platform and version
  • Full error logs
  • Relevant configuration files
  • Steps to reproduce the issue

Build docs developers (and LLMs) love

Get started for freeTalk to us