Troubleshooting

Complete guide to resolving common plugin issues.

🚨 Common issues

1. No HUD appears in dialogue

Symptom: The BetonQuest dialogue displays in classic chat instead of the HUD.

Possible causes:

Cause	Check	Solution
ConversationIO not configured	Check plugins/BetonQuest/config.yml	Add kg_bqhud to conversation.default_io
Plugin not loaded	Console at startup	Check for loading errors
BetonQuest missing	/plugins in-game	Install BetonQuest
Conflict with old KG_Hud	/plugins in-game	Remove the old kg_hud plugin

Detailed solution:

1. Open plugins/BetonQuest/config.yml
2. Find the conversation: section
3. Edit it:

conversation:
  default_io: kg_bqhud,menu,chest

4. Restart the server or run /betonquest reload
5. Test with a conversation

Alternative for a specific conversation:

# In your BetonQuest conversation file
conversationIO: kg_bqhud

2. The resource pack does not load

Symptom: The HUD does not display backgrounds/avatars, or you get a "Failed to load resource pack" error.

folder mode

Problem: The generated pack is not applied to players.

Solution:

1. Check that the folder exists:

   plugins/KGInfoServs-BQBetterHud/resourcepack/

2. Integrate the content into your server pack:

   your-server-pack/
   ├── assets/
   │   └── kgbq/          # Copy from resourcepack/assets/kgbq/
   └── pack.mcmeta

3. Rebuild and republish your server pack

4. Players must download the new pack

self-host mode

Problem: The plugin hosts the pack but players do not receive it.

Checks:

1. Accessible port:

   standalone:
     resource-pack:
       self-host-port: 8164  # Must be open on your firewall

2. Public URL configured (recommended):

   standalone:
     resource-pack:
       public-url: "https://your-domain.com"
       # or
       public-url: "my-server.example.com:8164"

3. Test access to the pack:

   • URL: http://your-ip:8164/pack.zip
   • The pack should download

4. Check the logs:

   [PackServer] HTTP server started on port 8164
   [PackSender] Sending pack to player: PlayerName

Firewall issue:

If the port is blocked:

1. Open port 8164 (TCP) on your firewall
2. Check the iptables rules (Linux)
3. Configure port forwarding (hosting provider)

3. Avatars are not displayed

Symptom: nameless.png displays for every NPC, or there is no avatar at all.

Causes and solutions:

Cause 1: Incorrect file name

❌ Incorrect:

plugins/KGInfoServs-BQBetterHud/avatars/
├── André.png          # Uppercase + accent
├── village merchant.png  # Space
└── Jose.PNG           # Uppercase extension

✅ Correct:

plugins/KGInfoServs-BQBetterHud/avatars/
├── andre.png
├── village_merchant.png
└── jose.png

Cause 2: npc_id misidentified

Check that your file name matches the automatic mapping:

Mapping reminder:

BetonQuest name	npc_id	File
André, the Blacksmith	andre	andre.png
José María	jose	jose.png
Müller Schmidt	muller	muller.png

The plugin automatically converts:

• To lowercase
• Removes accents
• Keeps only the first word

Cause 3: Corrupted PNG file

Test:

Open the PNG file with an image editor. If it does not open, the file is corrupted.

Solution:

Re-export the image as PNG with reliable software (GIMP, Photoshop, Paint.NET).

Cause 4: Pack not reloaded

Solution:

/bqhud reload

In folder mode, rebuild and republish your server pack.

4. Backgrounds do not change

Symptom: Custom backgrounds are not applied.

Checklist:

• Files placed in plugins/KGInfoServs-BQBetterHud/backgrounds/
• Exact names (respect case) :
  • dialogue.png
  • answer.png
  • hand.png
  • name_start.png
  • name_mid.png
  • name_end.png
• Valid PNG format
• /bqhud reload executed
• Server pack rebuilt (folder mode)

Quick check:

# List the background files
ls plugins/KGInfoServs-BQBetterHud/backgrounds/

Check that the names match exactly.

5. Positions/scale do not apply

Symptom: Changes to config.yml do not change anything visually.

Possible causes:

Cause 1: YAML syntax error

Example error:

# ❌ Incorrect (tabs used)
standalone:
	layout:
		avatar:
			x: -20

# ✅ Correct (spaces used)
standalone:
  layout:
    avatar:
      x: -20

Solution:

1. Check the YAML syntax with an online validator
2. Use spaces (no tabs)
3. Check the logs after /bqhud reload for errors

Cause 2: Out-of-range values

Some values may be ignored if outside reasonable limits.

Recommended values:

Parameter	Min	Max	Default
x-offset	-500	500	0
y-offset	-400	0	-200
scale	0.1	3.0	1.0

Cause 3: Client cache

Solution:

1. Run /bqhud reload on the server
2. The player reconnects
3. Or force a resource pack reload (F3 + T in-game)

6. Custom font does not display

Symptom: The text uses the default font despite the fonts.yml configuration.

Checks:

1. TTF file placed correctly:

   plugins/KGInfoServs-BQBetterHud/fonts/myfont.ttf

2. Correct configuration in fonts.yml:

   default:
     scale: 16
     file: "myfont.ttf"  # Exact file name
     use-unifont: false

3. Logs after /bqhud reload:

   [FontManager] Loading font: myfont.ttf
   [FontManager] Font loaded successfully

Common errors:

Error in logs	Cause	Solution
Font file not found: myfont.ttf	Missing file	Check the path and name
Failed to load font: invalid format	Corrupted TTF	Download a new file
Font rendering error	Java incompatibility	Use a standard TTF font

7. Typewriter effect does not work

Symptom: The text displays instantly instead of the typewriter effect.

Check:

typewriter:
  enabled: true   # Must be true
  speed: 30       # Characters per second (adjust if needed)

Recommended speeds:

• 10: Very slow (dramatic effect)
• 30: Normal (default)
• 60: Fast
• 100: Very fast

Note: If enabled: false, the text displays instantly.

8. fixed selection mode does not work

Symptom: fixed mode changes nothing, it is still in scroll mode.

Required configuration:

selection-mode: "fixed"  # Not "Fixed" or "FIXED"

Visual differences:

Mode	Behavior
scroll	Scrolling list, selected option highlighted in color
fixed	Fixed list, hand indicator (hand.png)

If you do not see the hand in fixed mode, check that backgrounds/hand.png exists.

9. /bqhud command denied

Symptom: "You don't have permission to use this command"

Solution:

Add the permission to your group or player:

# In your permissions plugin (LuckPerms, etc.)
permissions:
  - bqhud.admin

Quick test (OP only):

/op YourName
/bqhud reload

10. License error on startup

Symptom: The plugin does not load and displays a license error.

Possible error messages:

[BQBetterHud] License validation failed
[BQBetterHud] License key not found
[BQBetterHud] Unable to contact license server

Solutions:

1. Check the license file:

   plugins/KGInfoServs-BQBetterHud/license.key

2. File content:

   • A single line
   • No spaces before/after
   • Valid UUID format

3. Internet access: The server must be able to contact the license server. Check:

   • Outbound firewall
   • Server's internet connection
   • Proxy, if applicable

4. Contact support: If the problem persists, contact KGInfoServs on Discord.

🔧 Diagnostic tools

Check the plugin status

/plugins
# Look for "KGInfoServs-BQBetterHud" in green

View live logs

Linux:

tail -f logs/latest.log | grep -i bqhud

Windows (PowerShell):

Get-Content logs/latest.log -Wait | Select-String -Pattern "bqhud" -CaseSensitive:$false

Test a BetonQuest conversation

/q conversation <conversation_name> <player>

Force a resource pack reload (client)

In-game, press F3 + T to reload resources.

📋 Quick troubleshooting checklist

Before asking for help, check:

• plugins/BetonQuest/config.yml contains kg_bqhud in conversation.default_io
• /bqhud reload executed after each change
• Resource pack mode correctly configured (folder or self-host)
• Avatars/backgrounds in the right locations with the right names
• Server logs checked for errors
• bqhud.admin permission granted
• BetonQuest installed and working
• Supported Minecraft version (1.21+)

🆘 Getting help

If the problem persists after following this guide:

1. Gather the information:

   • Minecraft version
   • Paper/Spigot version
   • BetonQuest version
   • KG_BQBetterHud version
   • Server logs (last 50 lines with errors)
   • Your config.yml

2. Contact support:

   • KGInfoServs Discord: https://discord.gg/SZhD9AGUXW
   • Create a ticket with all the information above

📚 See also

• Configuration
• Avatars and Backgrounds
• Visual Customization
• Installation