Skip to content

troubleshooting.md

Latest commit

 

History

History
132 lines (91 loc) · 3.1 KB

troubleshooting.md

File metadata and controls

132 lines (91 loc) · 3.1 KB
Raw

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.