PlaceholderAPI Setup: Add Expansions and Fix Raw Placeholders

This guide is for server owners whose chat, menus or displays show raw text such as %player_name%. By the end, you will know how to check PlaceholderAPI support, find the required expansion and test a placeholder before putting it into a plugin config.

Check what PlaceholderAPI actually supplies#

PlaceholderAPI is a free, open-source plugin that lets supporting plugins display information through a shared placeholder format. Its listing advertises more than 230 expansions, but installing the main plugin does not establish that every placeholder you want is available.

PlaceholderAPI Free A free plugin by HelpChat that lets supporting plugins display shared information through placeholders and downloadable expansions. On SpigotMC

There are three parts to check:

• The displaying plugin: the plugin responsible for the chat message, menu or display must support PlaceholderAPI in that particular setting.
• The provider: the placeholder may come from another plugin directly, an eCloud expansion or an externally downloaded expansion.
• The token: use the exact placeholder documented by its provider, including both percent signs.

If you are choosing the plugin that will display the information, our chat plugin comparison and hologram plugin comparison can help you narrow the job down first. Then check that plugin's documentation for the exact field you intend to edit.

Check compatibility before installing#

The researched listings do not show identical version ranges. SpigotMC and Modrinth list support through Minecraft 26.3, while Hangar lists through 26.2. Check the listing and the build you intend to use against your server version rather than treating all three listings as interchangeable.

Get the plugin from its official SpigotMC listing or another official listing. Upload the jar to the server's plugins folder, restart the server and confirm that PlaceholderAPI loaded.

Find the expansion before downloading it#

Start with the official placeholder listSource site. Find the exact token you want and read its requirements. The usage guideSource site distinguishes three ways a provider can be supplied:

• Built into another plugin: follow that plugin's instructions rather than assuming there is a separate eCloud download.
• Available through eCloud: use the documented expansion name with the download command.
• Available externally: follow the linked provider's instructions. The usage guide also documents installing expansion jars in the expansions folder.

Keep the name of an expansion separate from the full placeholder token. The download command takes an expansion name; a parse test takes the text containing the placeholder.

Download an expansion and test its output#

The first commands below check the installed PlaceholderAPI version and active expansions. Replace <expansion> with the name identified in the official list, and replace <player> with the player whose context you want to test. Do not type the angle brackets.

After /papi ecloud download <expansion>, you must run /papi reload to register the downloaded expansion. Then check /papi list before testing its placeholders.

The final command uses %player_name%, the example shown in the command documentation. Check that token's provider requirements before expecting a result.

/papi version
/papi list
/papi ecloud info <expansion>
/papi ecloud download <expansion>
/papi reload
/papi list
/papi parse <player> %player_name%

/papi version
/papi list
/papi ecloud info <expansion>
/papi ecloud download <expansion>
/papi reload
/papi list
/papi parse <player> %player_name%

/papi version
/papi list
/papi ecloud info <expansion>
/papi ecloud download <expansion>
/papi reload
/papi list
/papi parse <player> %player_name%

The command referenceSource site also documents me as the player argument when testing your own context in game. Check the returned text before moving on: the parse command is the direct test, separate from the plugin that will eventually display it.

Put the tested token into a supported config field#

Once the parse test returns the information you expect, place the same token into a config option that explicitly supports PlaceholderAPI. The documented format is %expansion_placeholder%, with a percent sign at each end.

1. Identify the exact message or display field you want to change.
2. Confirm that field supports PlaceholderAPI.
3. Copy the tested token exactly.
4. Follow the displaying plugin's instructions for applying its config changes.
5. Check the result in the actual display, using the player context you tested.

A successful parse test and a successful display check answer different questions. The first checks the placeholder through PlaceholderAPI; the second checks that the chosen plugin uses it in the intended place.

Work through raw placeholders in a fixed order#

When a token remains visible as plain text, use this checklist before changing several settings at once.

1. Check the token against its documentation. Confirm the spelling, percent signs and any required arguments.
2. Check its provider. Establish whether it is built into a plugin, supplied through eCloud or distributed externally.
3. Register downloaded eCloud expansions. After /papi ecloud download <expansion>, run /papi reload. Downloaded expansions will not be properly registered without this step.
4. Check the active expansion list. Run /papi list and compare it with the requirements you found rather than assuming a download completed the whole setup.
5. Repeat the parse test. Use the same player and token as the display you are investigating.
6. Check the destination field. Confirm support for PlaceholderAPI in that specific config option.

When an eCloud download fails#

The usage guide says the server needs internet access to api.extendedclip.com to download eCloud expansions. Check the expansion name against the official list, then include the exact error when asking your host about outbound access. A hosting-panel owner may need the host to check that connection.

When a reload is required#

The command reference says /papi reload must be run after downloading eCloud expansions so they are properly registered. Run it after the download, check /papi list, then repeat the same parse test. Continue checking provider requirements and the displaying plugin's own instructions if the token still does not resolve.