DeerFolia · Troubleshooting

Check the problem layer

Check the problem in this order:

1. Java and the startup command;
2. the core jar and patch loading;
3. DeerFolia configuration;
4. Folia plugin compatibility;
5. one dense region or one feature.

Change one variable at a time. Keep the complete startup log, a configuration backup, and the steps that reproduce the problem.

The core does not start

Check these items:

• java -version reports the runtime required by the selected release;
• the command references the DeerFolia jar, not Paper, Purpur, or an older Folia jar;
• the jar matches the server release;
• eula.txt is accepted as required;
• the server user can read and write the directory;
• the log is not stopping on YAML, dependency, or patch errors before DeerFolia configuration is generated.

Do not put the core in plugins/, and do not pass two server-core jars in one command.

Configuration errors

Stop the server. Copy the current file. Restore the last known-good backup. Check:

• Tab indentation;
• spaces after colons;
• quotes around messages containing colons, hashes, or braces;
• list and empty-list syntax;
• numbers accidentally written as quoted text.

Add changes one at a time. Restart the server after you edit either deer-folia.yml or kaiiju-entity-throttling.yml.

A plugin does not load

Folia can reject plugins without explicit Folia support. A plugin can also fail when it accesses data outside its current region. Read the plugin compatibility statement and the startup log. Paper support does not prove DeerFolia support.

Reproduce the problem with an empty plugin directory or only the core plugins. Add plugins one at a time after the problem disappears. Include the core build identifier, server release, Java runtime, affected plugin builds, and the full stack trace in a report.

A farm or villager area is slower

Do not change every optimization at once. Follow these steps:

1. Check whether the target region is above an entity-throttling limit.
2. Disable kaiiju-entity-throttling for a test.
3. Check Dynamic Activation start-distance, activation-distance-mod, and maximum-activation-prio.
4. Check POI intervals in villager areas.
5. Restore one feature at a time. Record output, CPU, and logs.

Do not use removal as a permanent way to clean up normal production entities. Trading halls, iron farms, and item sorters need a limit and removal value with enough headroom.

Pathfinding or entity movement looks wrong

Disable async-pathfinding on a test server. If the symptom disappears, set a smaller async-pathfinding-max-threads value. Increase it in small steps. Also check whether a plugin reads entities or chunks across regions.

An AFK player is out of sync after resuming

Check these values:

• afk-network-optimization.enabled is true;
• resync-on-resume is true;
• necessary categories were not mistakenly added to suppression-whitelist-categories;
• max-suppressed-bytes-before-category-resync was not set so low that it causes constant refreshes;
• the problem is not limited to one proxy, compression, or protocol-plugin combination.

Ask the player to move once. Check whether chunks and entities recover. An administrator can use /afknetstats to check whether statistics still increase.

What to include in a useful report

Include these details:

• core build identifier, server release, and Java runtime;
• startup command and complete startup log;
• relevant configuration with passwords, tokens, and private data removed;
• affected plugins and their build identifiers;
• reproduction steps, frequency, and expected behavior;
• whether the issue occurs only on Folia/DeerFolia;
• recent configuration changes and the result of a rollback test.