Troubleshooting

Start with:

/hdb version
/hdb status
/hdb verify
/hdb debug
/hdb report

/hdb debug provides concise user-facing diagnostics. /hdb report creates a more complete support report; players can click to copy it, while console users can copy the logged output.

Plugin does not start

Check	Fix
Java version	Use Java 25 or newer.
Server type	Use a supported modern Paper or Folia server.
JAR placement	Put one HeadDB JAR directly in plugins/.
Duplicate JARs	Remove old duplicate versions.
Configuration	Check the first HeadDB configuration error in console.

Database unavailable

Likely causes:

• First startup has no cache and remote refresh failed.
• Outbound network access is blocked.
• HTTP timeouts are too low for the environment.
• The cache was removed and the remote source is unavailable.
• The server cannot write to plugins/HeadDB/.

Recommended sequence:

1. Check server network access.
2. Run /hdb verify.
3. Run /hdb refresh.
4. Inspect /hdb report.
5. Increase HTTP timeout values only when justified.
6. Verify filesystem permissions.

Why does status say LOADED from CACHE?

This is normal when HeadDB loads verified local artifacts during startup. If the remote manifest is unchanged, HeadDB keeps the cache-backed snapshot instead of re-downloading the full catalog.

The last refresh operation in /hdb debug or /hdb report confirms whether a remote check completed.

Scheduled refresh does not appear to run

Check:

refresh:
  scheduled:
    enabled: true
    interval-hours: 6

The first scheduled run occurs after the configured interval; startup refresh already performs the initial check. Inspect /hdb report for scheduler configuration and the last refresh operation.

Configuration fails to load

Common causes:

• YAML indentation errors
• Tabs instead of spaces
• Invalid booleans or numbers
• Invalid relative paths
• Invalid materials in gui.yml
• Invalid sound identifiers in sounds.yml
• Scheduled interval outside 1 through 168 hours

Restore from backup, compare with generated defaults, and use the exact key named in the console error.

GUI opens but players cannot take heads

Check:

headdb.head.take
headdb.gui.head.take

Also check category access. When economy is enabled, verify balance, Vault, the economy provider, and applicable prices.

Search returns no results

Check database state, query spelling, active filters, local visibility overrides, and category permissions.

Favorites do not work

Check:

headdb.favorites
headdb.gui.favorites
headdb.gui.favorites.toggle

Favorites require writable local storage.

Player heads do not work

Check:

player-heads:
  enabled: true
  allow-external-lookup: true

and permissions:

headdb.player-heads
headdb.command.player
headdb.gui.player-heads

Targeting other players requires the corresponding .others permission.

Local content disappeared

Check whether this file was deleted or replaced:

plugins/HeadDB/storage/headdb.db

Restore it from backup when available.