FAQ

What server software does HeadDB support?

HeadDB supports modern Paper and Folia servers.

What Java version is required?

The Paper/Folia plugin requires Java 25 or newer. The API and core modules target Java 21.

Does HeadDB require Vault?

No. Vault is optional and is required only when economy support is enabled.

Does HeadDB work without internet access?

A new installation needs network access to download the public database. After a successful download, HeadDB can load the last verified local cache while the remote service is unavailable.

What happens if a refresh fails?

The active verified database remains available when one was already loaded. HeadDB records the failure without replacing the working snapshot.

Useful commands:

/hdb status
/hdb verify
/hdb refresh
/hdb report

Why does the database source say CACHE after a successful remote refresh?

HeadDB may load verified artifacts from disk and then confirm through the remote manifest that they are unchanged. No full download is needed, so the active snapshot remains cache-sourced.

How often does HeadDB check for new heads?

Scheduled checks are enabled by default every six hours. Configure the interval under refresh.scheduled in config.yml.

Can I hide or edit public heads?

Yes. Authorized administrators can apply local visibility and metadata overrides. These changes affect only that server.

What are Custom Heads?

Custom Heads are server-local heads created and managed by staff. They may be saved as drafts and published later.

What are Custom Categories?

Custom Categories are server-local categories that appear alongside public categories and organize remote or local content.

Why do some permissions still say more-heads or more-categories?

Those identifiers are retained for backward compatibility. The current public feature names are Custom Heads and Custom Categories.

Are favorites global?

No. Favorites are stored per player on the server.

Why does /hdb update require a restart?

A running JVM cannot load the replacement plugin classes safely. HeadDB downloads or stages the JAR, then the server must restart to load it.

Should automatic plugin installation be enabled?

Production servers commonly keep it disabled and use notifications plus a controlled restart. Database updates are separate and can refresh automatically without replacing the plugin JAR.

What should be backed up?

Back up:

config.yml
gui.yml
sounds.yml
economy.yml
messages/
storage/headdb.db

Can another plugin use HeadDB?

Yes. Integrate through headdb-api and Bukkit's service provider system rather than depending on internal Paper classes or reading cache/storage files directly.