How to Set Up LuckPerms on a Paper Server

Design the permission model before installing

LuckPerms controls permission checks made by Paper and its plugins. It does not add commands by itself, replace the whitelist or make every operator action safe to delegate. Begin by listing the real roles on the server and the tasks each role needs. A small community often needs only default players, moderators and administrators. Add a builder, event or supporter group only when it represents a stable bundle of access rather than one person's temporary exception.

Plan inheritance from least to most privileged. The default group holds ordinary player permissions, moderator inherits default, and administrator inherits moderator. This avoids copying the same nodes into several places and makes removal predictable. Keep direct user permissions rare; they are harder to review than group membership and can survive after a staff role changes. LuckPerms values can be true, false or undefined, so document deliberate denials as well as grants instead of assuming every missing node behaves identically in every plugin.

Record the current Paper build, Java runtime, plugin list, operators and any existing permission plugin. LuckPerms says it should be the only permission plugin handling checks after a migration. Stop Paper and take a complete restorable backup before replacing an access-control system, including plugins, their data, worlds and external databases. The review process in /blog/install-plugins-paper-minecraft-server applies because a permission JAR runs with the server account's access.

• List roles and the exact commands or features each one needs.
• Build inheritance upward from default instead of duplicating nodes.
• Reserve direct user grants for narrow, documented exceptions.
• Back up the stopped server and preserve the previous permission state.

Install the correct LuckPerms build on Paper

Download the Bukkit-compatible LuckPerms JAR from the project's official download page. With Paper fully stopped, place exactly one LuckPerms JAR directly in the plugins directory. Remove an older active LuckPerms JAR before starting, but retain it with the offline backup. Do not upload the Fabric, Forge, Velocity or BungeeCord artifact to a Paper backend, and do not keep a second permission plugin active after any planned import is complete.

Start Paper normally and read the log from the first line. LuckPerms should enable and create its folder, configuration and storage files without a Java, dependency or database error. Its default storage is H2, held in the LuckPerms data directory, and that local database is appropriate for a single server. Do not delete or hand-edit the database because a panel shows an unfamiliar binary filename. Stop again before changing configuration and keep the generated comments with the file.

Use the server console for bootstrap access. Run lp user YOURNAME permission set luckperms.* true only for a secured recovery administrator who must configure LuckPerms, then continue with ordinary groups instead of handing that wildcard to staff. On Bukkit-family servers, operator behavior can also depend on the LuckPerms configuration, so the console remains the dependable recovery path. Confirm that /lp now lists the commands expected for the administrator before making broader changes.

• Use the official Bukkit/Paper artifact and one active JAR.
• Verify the complete first startup, generated configuration and H2 database.
• Bootstrap from the console and restrict luckperms.* to a recovery administrator.
• Keep the old JAR and data in the backup, not beside the live plugin.

Create groups and inheritance from the console

Create the structure before adding people. Run lp creategroup moderator and lp creategroup administrator, then make moderator inherit default with lp group moderator parent add default. Make administrator inherit moderator with lp group administrator parent add moderator. LuckPerms inheritance is recursive, so administrators receive moderator and default permissions without three separate copies. Use lp group moderator info and lp group administrator info to verify the parents before assigning nodes.

Grant permissions to the lowest group that should have them. A documented plugin node might be added with lp group moderator permission set example.moderate true. Use the exact node from that plugin's current documentation; example.moderate is only a placeholder and should never be copied into production. Remove an entry with permission unset rather than setting random false nodes until a command disappears. An explicit false is a deliberate denial and can override an inherited grant, while unset returns the decision to inheritance and the plugin's default.

Add a test account with lp user PLAYER parent add moderator, then confirm membership with lp user PLAYER info. Use parent remove to revoke a role. Avoid parent set during the first rollout because it replaces existing parents and can remove access you meant to retain. Keep the operator list separate: membership in an administrator group should be intentional, reviewable and sufficient for its tasks without requiring every administrator to be a Minecraft operator.

• Create groups first, then add parent relationships from least to most privileged.
• Assign each permission once at the lowest group that needs it.
• Use unset to remove a node; use false only for a deliberate denial.
• Test group membership with an ordinary account before migrating staff.

Use the web editor without skipping review

LuckPerms includes a hosted web editor for every storage type. Run lp editor groups to open only group data, lp editor users for user data, or lp group moderator editor for one group. The server creates a session and returns a link. Open it in a trusted browser, select the intended group, add permission or parent nodes and check each value and context before saving. Suggestions are convenient but not exhaustive; a missing suggestion does not prove that a node is invalid.

The editor's Save button does not immediately rewrite the server. It produces an apply command that must be run in the Paper console or by an authorized administrator. Read the generated summary before applying it. If it removes unexpected parents, touches users outside the change or contains a broad wildcard, discard the session and start with a narrower scope. Treat session links and apply commands as administrative change material rather than posting them in public chat or tickets.

After applying, run lp log recent and the relevant group info command, then exercise one affected feature with a test account. The editor improves visibility; it does not replace backups, peer review or an acceptance test. Console commands remain available when the external editor cannot be reached, and a production permission change should not depend on weakening outbound or browser security controls.

Find exact permission nodes with verbose

Start with the documentation for Paper or the plugin that owns the command. Permission names belong to the software performing the check, not to LuckPerms. When documentation is absent or the result is surprising, use LuckPerms verbose during one controlled action. Run lp verbose record PLAYER, ask that test account to perform the command once, then run lp verbose upload to stop recording and open the report. A filter keeps unrelated checks out of a busy-server trace.

Follow the report to the permission that was checked, its result and the source plugin. Grant that exact node to a staging group, repeat the action and inspect it again. Do not solve one missing command with plugin.*, minecraft.* or another broad wildcard. A wildcard can silently include destructive features added by a later plugin update, while one exact node expresses the access decision you actually reviewed.

If the client lags while verbose output is printed live, keep record mode instead of streaming every check into chat. Turn verbose off or upload as soon as the test ends. Use lp user PLAYER permission check NODE to inspect a known node, and compare the user's current parents and contexts. Capture the plugin version, test action and result so the next permissions incident starts with evidence instead of another speculative grant.

• Prefer the owning plugin's current permission reference.
• Record one test user's one action, then upload and inspect the trace.
• Grant the narrow checked node and repeat the same acceptance step.
• Stop verbose promptly and keep reports away from public channels.

Scope contexts and prefixes deliberately

A context limits where a permission, parent or metadata value applies. For example, append world=world_nether to grant a node only in that world, or server=survival to scope it to the server name configured in LuckPerms. Contexts can be combined, so lp group moderator permission set example.fly true server=events world=build_world requires the applicable server and world circumstances. Test the player while online because offline users do not have a live context set to inspect.

Use contexts only when the role genuinely changes by world, server or game mode. A maze of exceptions is harder to audit than a few clear groups. Check the configured server name before using server contexts, and remember that a permission may need separate entries or context values for several locations. The web editor exposes context columns; review them carefully because a correct node in the wrong context appears broken to the player.

Prefixes are metadata, not chat rendering. LuckPerms can store a prefix such as lp group moderator meta addprefix 100 "[Mod] " and selects higher-priority values first, but it does not format Paper chat by itself. A compatible chat or display plugin must read the metadata, commonly through Vault on Bukkit-family servers. If the permission works but the label is absent, inspect lp user PLAYER meta info and the formatter integration instead of repeatedly changing group inheritance.

Validate, back up and scale the permission system

Build a small test matrix with default, moderator and administrator accounts. Join as each non-operator account, run allowed and denied commands, cross any context boundaries, reconnect and restart Paper. Verify that denied actions fail without exposing unrelated commands, and confirm that a removed parent stays removed after restart. Check lp log recent for the expected administrator changes and keep the console recovery account available until the rollout has passed a real busy period.

Back up the entire LuckPerms data directory and configuration with the server. For one Paper instance, the default H2 store avoids an external database. A network that must share permissions between several backends needs a supported remote storage type connected consistently, plus update propagation so other processes learn about changes. Installing LuckPerms only on Velocity does not control permission checks made by Paper plugins; each relevant backend needs its own compatible LuckPerms installation and network design.

Define rollback triggers such as staff losing essential moderation, ordinary players receiving administrative access, repeated storage errors or contexts applying on the wrong server. Stop Paper, preserve logs and restore the coherent previous plugin data and configuration rather than editing the database during an incident. More administration guides are collected at /blog. If the verified network needs shared database access, isolated staging or operational support beyond the current setup, compare the documented options at /pricing after the permission model itself is proven.

• Test every role as a non-operator before moving real staff into it.
• Repeat grants, denials, contexts and membership checks after a restart.
• Back up configuration and storage together and preserve audit logs.
• Use remote storage and propagation only for a deliberately designed network.