Troubleshooting and backups

Start with these checks

1. Check Minecraft 1.21.8, Java 21 or newer, Fabric Loader 0.19.3 or newer, and Fabric API 0.136.1+1.21.8 or a compatible newer build for 1.21.8.
2. Use the same ArdaNPCs version on the server and every client. Keep only one version of its JAR in mods/.
3. Check that you are launching the intended profile and world. NPC data belongs to a specific world.
4. Read the in-game error and the relevant part of logs/latest.log on both server and client.

Editor access and permissions

NPC administration, appearance editing and script editing require operator permission level 2 or higher. Creative mode alone does not provide these permissions.

• If a command is missing or denied, ask the server administrator to check your account's permissions.
• Run /ardanpcs manager in-game as an authorised player. The manager is a client GUI and cannot open in the server console.
• If the command reports a missing client mod, check that ArdaNPCs and Fabric API are installed in your game profile too.
• After changing the version or modpack, reconnect with the correct set of mods.

A change was not saved or disappeared after restart

1. Complete the relevant save action: Save appearance for skins and capes, the script panel's Save for scripts, or apply the model selection and then save the main editor.
2. Read the confirmation or error. A preview or an edited field does not confirm a disk write.
3. If two editors conflict, review your draft against the current state before saving again.
4. For a write failure, check free disk space, the server process's file permissions and file locks. In the server log, look for the exact path and messages such as Failed to write or Cannot safely load.

NPC definitions live at <world>/data/ardanpcs/npcs.json. A different world or server instance uses a different NPC collection. This file alone does not contain every quest, player or inventory record.

The storage system uses .bak files. If a primary JSON is damaged, it tries a valid backup and preserves the damaged bytes in a .corrupt-* file. If neither primary nor backup is valid, loading fails instead of replacing the data with an empty collection.

Do not delete damaged stores or replace them with empty JSON to clear an error. Stop the server, preserve a copy of the entire world and log, then restore a verified backup. Make manual data repairs while the server is stopped. Reload is not a backup or an undo command.

A skin, cape or model is missing

Player skin or PNG

• Skins and capes apply to the humanoid body. A selected mob model uses that mob's renderer.
• For a player profile, use Look up player followed by Save appearance. Check the name/UUID; retry later if the official service is unavailable.
• For imports, check the server's config/arda_npcs/import_textures/ folder, actual PNG format and maximum size of 256 KiB. Skins must be 64 × 64 or 64 × 32 pixels; capes must be 64 × 32.
• If a file is missing from the picker, try a simple name such as guard.png and refresh the list. Do not use subdirectories or directory links. The list shows at most 64 files.
• If the import quota is full, do not delete random world assets: other NPCs, templates or corpses may reference them. The world limit is 1024 assets and 64 MiB of content. Plan further changes using a backup and an inventory of textures in use.
• For resource packs, check the identifier and that clients have the same texture. For URLs, check a direct, reachable PNG address; capes require HTTPS.

For the setup and import procedure, see Appearance, skins and models.

An entity model reverted to a humanoid

1. Check the full entity ID and that its mod is installed on both server and client.
2. Select the model again, apply the selection and save the main editor.
3. Check the client log for a model creation or rendering failure. ArdaNPCs uses its default appearance after such a failure.
4. Try another entity from the same mod. Its custom renderer may need state the helper model does not supply.
5. After resolving the cause, restart the client and try the model again; failed types are remembered during the client session.

A missing special animation does not necessarily mean the model failed to save. The NPC does not inherit the other entity's AI or abilities, and universal GeckoLib compatibility is not guaranteed. A larger hitbox does not teach an NPC to fly or use the original mob's attacks.

A script does nothing or has been disabled

1. Open the NPC's Scripts panel. Check that scripting is enabled and that the intended event contains code.
2. Enter the event body, not a wrapper event function copied from another mod.
3. Run Check. Fix reported syntax problems or unsupported API calls.
4. Run Test for the chosen event. This is a simulation, not an actual reward grant or world change.
5. Click Output and read the Diagnostics and result panel. It shows the last error and a limited api.log history.
6. Save after fixing the script. A successful save clears the stored failure block and allows execution to resume.

ArdaNPCs uses its own restricted server-side JavaScript API. CustomNPCs scripts are not drop-in compatible. Review and fix unsupported operations reported by the importer; conversion does not prove a script works in every modpack.

For a shared execution budget warning, reduce frequent events, lengthy loops and effects. Do not use tight retry loops instead of timers. A predicate is read-only and must not change the world or stored variables.

If diagnostics report Script runtime unavailable: storage could not be loaded safely, resolve the data-loading problem and inspect the server log first. Script runtime state is stored at <world>/data/ardanpcs/scripts-state.json; do not clear it as the first troubleshooting step.

Back up and update

1. Exit the game or stop the server normally, and wait for saving to finish.
2. Copy the entire world. Include vanilla player data, mod data and data/ardanpcs/appearance-assets/.
3. Keep the active configuration, mod versions and any custom resource packs as well. Source PNGs for future imports live outside the world in config/arda_npcs/import_textures/.
4. Try the new version on a separate copy of the world first. Update ArdaNPCs on server and clients and remove the old JAR from the active mods/ directory.
5. Check the editor, a dialogue/quest, saving across a restart, appearance on a second client and the services you actually use.

npcs.json alone is not a complete server backup. Templates live at <world>/data/ardanpcs/templates.json, and imported images have separate files. Moving only the JSON to a different world does not move those images.

To return to an older version, restore the matching complete world backup and mod set. Replacing the JAR alone does not undo changes to saved data. Individual .bak files help recover stores but do not replace a full world backup.

What to include in a bug report

• Minecraft, ArdaNPCs, Fabric Loader and Fabric API versions, and whether you are playing singleplayer or on a server.
• Short steps from opening the editor to the failure, plus the expected result.
• For a model problem, the exact entity ID and the supplying mod's name and version.
• For a script problem, the event, a short relevant code sample and the diagnostic message.
• The relevant client or server log section from the time of the problem. Remove private details and login information before posting it.