> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/configuration-and-administration/faq.md).

# FAQ and troubleshooting

Record your server, client version, command and complete error before investigating. Back up affected files before editing. Validate and reload changes, then reopen the menu to check the result.

## Installation and configuration

### The plugin does not enable

Check startup logs and the [requirements](/arcmenu-wiki/getting-started/requirements.md). Keep only one ArcMenu plugin file in `plugins/`. Spigot also downloads required files on first startup; check connectivity and restart if the download fails.

Replacing the plugin file requires a server restart. Configuration reload cannot replace it.

### Configuration changes do not appear

Check the directory: Paper-family servers use `plugins/ArcMenu/menus/`, while Spigot uses `plugins/ArcMenu/spigot/menus/`. Run `/arcmenu validate`, correct reported errors and run `/arcmenu reload`.

Image, template and tooltip-style changes require a full reload as described in [Configuration files](/arcmenu-wiki/configuration-and-administration/configuration-files.md). Image changes also require updating the resource pack loaded by players.

### Menu validation fails

Use the reported filename and field to locate the problem. Check YAML indentation, value types, duplicate menu IDs, invalid navigation targets and whether exactly one menu has `main-menu: true`.

Start with a complete example and edit it gradually instead of combining every fragment from a reference page. On Spigot, also check for unsupported fields and actions in [Platform and plugin compatibility](/arcmenu-wiki/configuration-and-administration/compatibility.md).

## Opening and using menus

### A player cannot open a menu

Players need `arcmenu.use` and any additional permission set by the menu's `permission` field. Test both administrator and ordinary player accounts; an OP being able to open a menu does not confirm ordinary players have permission.

Paper-family servers also require the player to be on the ground. Test `/arcmenu open <menu-id>` while grounded before investigating shortcuts.

### Shift+F does not open the main menu

Check that one main menu exists and `shortcuts.shift-f` is enabled. Paper-family settings are in `plugins/ArcMenu/config.yml`; Spigot shortcut settings are in `plugins/ArcMenu/spigot/config.yml`.

Check permissions, the client's swap-offhand key binding and other plugins using the same input. If the command works, continue testing through commands first.

### A visible button cannot be clicked

Frontend buttons and backend regions are configured separately. Check matching positions and dimensions, and whether the action uses left or right click. Frontend groups, scaling and animations do not automatically move backend regions.

For overlapping regions, check `priority` and conditions. A button can remain visible when its permission or condition is not satisfied. See [Backend regions and click events](/arcmenu-wiki/menu-configuration/menus/backend.md).

### Another plugin's command fails from a button

Have the same player run the command directly to check permissions, arguments, cooldowns and fees. `player` executes as the player; `console` executes as the console and requires explicit target-player arguments.

ArcMenu does not grant third-party permissions or guarantee command success. See the [Plugin integration menu example](/arcmenu-wiki/menu-examples/integration-menu.md).

## Images, mouse input and text

### Images are missing or outdated

Check that image references match PNG files in `images/`, with lowercase names and directories. Run `/arcmenu reload all` to rebuild resources and distribute the updated pack.

When using CraftEngine, also run `/ce reload all` and distribute its updated pack. Menu reload alone does not update client images, and ArcMenu does not automatically send the generated ZIP. See [Images and resource packs](/arcmenu-wiki/feature-configuration/resource-packs.md).

### Mouse mode cannot be selected

Spigot does not support mouse mode. Paper-family servers require a supported client and the accompanying resource pack. Players cannot select mouse mode when administrators force touch mode. Check `mouse.policy` and [Touch and mouse input](/arcmenu-wiki/feature-configuration/input-modes.md).

### A placeholder remains unchanged

Distinguish built-in placeholders from those supplied by other plugins. Third-party placeholders on Paper-family servers require PlaceholderAPI and the providing plugin or expansion. Spigot supports only the documented basic placeholders.

Check names, arguments and data keys, and confirm the data exists. ArcMenu's internal placeholders cannot simply be used as PlaceholderAPI placeholders in other plugins. See [Placeholders and text formatting](/arcmenu-wiki/text-formatting/text-placeholders.md) for text updates.

### Spigot's configuration has no language option

`plugins/ArcMenu/spigot/config.yml` only configures shortcuts. Language options are in `plugins/ArcMenu/config.yml`, with files in `plugins/ArcMenu/languages/`. Both server families use these language settings.

When client-language selection is enabled, changing the default may not change a particular player's messages. Disable `language.follow-player-locale` to use one language for everyone. Menu text is edited separately; see [Language management](/arcmenu-wiki/feature-configuration/languages.md).

## Visual editor

### The editor cannot be opened

Check that the server is Paper-based, the administrator has `arcmenu.admin`, the menu is loaded and the client has matching Fabric, Fabric API and ArcMenu Editor installations. Install a compatible editor if an update is requested.

See [Visual editor](/arcmenu-wiki/feature-configuration/editor.md) for downloads and instructions. If another administrator is editing the same menu, wait until they finish.

### The editor refuses to save

Check whether the message reports external changes to the menu file. End editing, reopen the current file and make your adjustments again. Also check configuration errors and file write permissions when saving fails.

Saved changes require applying or reloading before ordinary players use the updated menu. Exit the editor and open the menu normally to test button actions.

## Reporting a problem

Include server and Java versions, client version, the affected feature, reproduction steps, relevant configuration and the complete error. For image or editor issues, state whether the pack is updated and the matching editor is installed.

Remove passwords, tokens and private server addresses before sharing configuration. Preserve relevant indentation, fields and command arguments so the issue can be reproduced.