Tell whether a Minecraft plugin jar will actually survive on Folia
- by reading its bytecode, not its README.
Works on any jar - including one you did not compile. Server owners can check a paid plugin before installing it; developers can gate a release in CI and surface regional thread-safety bugs directly in GitHub's Security -> Code scanning tab.
Open Browser Drag-and-Drop JAR Scanner | GitHub Action (uses: SalyyS1/foliascan@main) | CLI Releases
Folia's threading changes are not gradual. Some very ordinary Bukkit calls stop working completely, and nothing tells you until a player triggers the code path:
- The entire legacy scheduler is dead. Folia inserts an unconditional
if (true) throw new UnsupportedOperationException()intoCraftScheduler#handle, so everyrunTask,runTaskLater,runTaskTimerand async variant throws. Not "on the wrong thread" - always. - The Scoreboard API is not implemented.
registerNewObjective,registerNewTeam,clearSlot,getNewScoreboardandPlayer#setScoreboardall throw unconditionally. Every scoreboard HUD, stat sidebar and team system breaks. - Runtime world creation is gone.
createWorldandunloadWorldthrow. - Synchronous teleports are rejected with
Must use teleportAsync while in region threading. Entity,World,BlockandBlockStatecalls are region-guarded. Folia wrapsCraftEntity#getHandle- and ~170 subclass overrides - in a thread check, so touching an entity from a thread that does not own it throws.
Adding folia-supported: true silences the loader, not the exceptions. FoliaScan finds the
call sites that will still blow up.
Inspect one .jar or drop an entire server plugins/ directory directly in your browser at
https://salyys1.github.io/foliascan/:
- Unpacks ZIP headers and
0xCAFEBABEJVM class constant pools locally usingArrayBufferandDecompressionStream('deflate-raw')with zero network uploads and zero external CDNs. - Evaluates
paper-plugin.yml/plugin.yml(FS001), automated bytecode patcher markers (FS002), unconditional Folia crashes (FS010throughFS041), NMS internals (FS070), andisPrimaryThreadgates (FS080), skipping shaded vendor packages unless toggled on. - Renders a multi-JAR Server Compatibility Matrix (
PASS,PATCHED,FAIL) with Markdown and JSON export, plus a 1-click synthesized sample plugin.jarfor instant testing.
For full intra-jar call-graph async taint propagation (FS050 through FS065, FS081 concurrency audit, FS082 through FS086 cross-region and lifecycle rules, and FS087 through FS090 Moonrise async chunk generation and block-entity rules),
baseline files, and OASIS SARIF v2.1.0 output (codeFlows + regional taint call-chain paths), run
the CLI or GitHub Action below.
Requires Java 21+.
Download foliascan-<version>.jar from
Releases and run it:
java -jar foliascan-1.0.0.jar MyPlugin.jarOr build from source:
./gradlew build # runs the test suite too
java -jar build/libs/foliascan-1.0.0.jar MyPlugin.jarfoliascan [OPTIONS] TARGET...
TARGET plugin jar(s), or a directory of jars
--format console|json|sarif output format (default: console)
-o, --output PATH write the report to a file
--sarif PATH write an OASIS SARIF 2.1.0 report to PATH
--fail-on LEVEL blocker|critical|warning|info|never (default: critical)
--all report relocated dependency packages too
--include PACKAGE only scan this package (repeatable)
--exclude PACKAGE skip this package (repeatable)
--disable RULE_ID turn a rule off (repeatable)
--baseline FILE suppress findings listed in FILE
--write-baseline FILE record current findings as accepted, then exit 0
--no-color plain output
-v, --verbose list every call site instead of the first 8
--rules print the rule catalog with sources, then exit
--benchmark run the synthetic multi-class bytecode benchmark suite and exit
--benchmark-runs INT timed passes for --benchmark (default: 20)
Exit codes: 0 clean at the chosen threshold, 1 findings at or above it, 2 bad usage.
Scan a whole server directory or emit a SARIF v2.1.0 report alongside console output:
foliascan /srv/mc/plugins --fail-on blocker
foliascan build/libs/MyPlugin.jar --sarif foliascan.sarifGate any Paper, Folia, or Spigot repository and publish Folia thread-safety bugs natively to the
GitHub Security -> Code scanning tab in 10 lines using the composite GitHub Action and
github/codeql-action/upload-sarif:
permissions:
contents: read
security-events: write
steps:
- uses: SalyyS1/foliascan@v1.0.0
with:
jar: build/libs/*.jar
sarif-file: foliascan.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: foliascan.sarifThe action caches foliascan-<version>.jar, publishes a Markdown compatibility matrix to
$GITHUB_STEP_SUMMARY, writes OASIS SARIF v2.1.0 (with tool.driver metadata, deduplicated rule
help, %SRCROOT% source paths, bytecode line numbers, and codeFlows regional taint call chains),
and exits with FoliaScan's threshold exit code.
| Input | Default | Purpose |
|---|---|---|
jar |
(required) | Plugin JAR path(s), glob pattern(s), or directory of JARs |
fail-on |
critical |
Lowest severity that exits non-zero (blocker, critical, warning, info, never) |
baseline |
"" |
Baseline JSON file path used to suppress accepted findings |
disable |
"" |
Comma- or space-separated rule IDs to turn off (for example FS063,FS070) |
all |
false |
Report relocated third-party dependency packages too |
sarif-file |
"" |
Optional output file path for a SARIF 2.1.0 report (also exposed as outputs.sarif-file) |
version |
1.0.0 |
FoliaScan release version to download and cache |
Or invoke the CLI JAR directly in any CI runner:
- name: Check Folia compatibility
run: |
java -jar foliascan-1.0.0.jar build/libs/*.jar \
--sarif foliascan.sarif --fail-on criticalAdopting on a large legacy plugin? Record what exists today and fail only on new problems:
foliascan MyPlugin.jar --write-baseline foliascan-baseline.json # once
foliascan MyPlugin.jar --baseline foliascan-baseline.json # every buildFingerprints deliberately exclude line numbers, and Baseline v2 records SHA-256 structural hashes
that normalise javac and kotlinc synthetic lambda ordinal suffixes (lambda$foo$0 -> lambda$foo$*),
so editing code or adding lambdas above a call site does not resurrect a suppressed finding.
Run foliascan --rules for the full text of each one, including the Folia source it came from.
| Id | Severity | What it catches |
|---|---|---|
| FS001 | blocker | descriptor missing folia-supported: true - Folia refuses to load the plugin |
| FS002 | warning | the folia-supported flag was written by a patcher, not by the author |
| FS010 | critical | Bukkit.getScheduler() / Server#getScheduler() |
| FS011 | critical | any call on BukkitScheduler, including via a stored field |
| FS012 | critical | class extends BukkitRunnable |
| FS020 | critical | synchronous Entity#teleport |
| FS030 | critical | Scoreboard#registerNewObjective / registerNewTeam / clearSlot |
| FS031 | critical | ScoreboardManager#getNewScoreboard, Player#setScoreboard |
| FS040 | critical | createWorld, unloadWorld |
| FS041 | critical | World#getTickableTileEntityCount |
| FS050 | warning | getTPS, getAverageTickTime read off-region |
| FS051 | warning | dispatchCommand off-region |
| FS060 | warning | region-guarded World calls (getChunkAt, loadChunk, unloadChunk, createExplosion, setBiome, ...) |
| FS061 | warning | region-guarded Block calls (getType, setType, getBlockData, setBlockData, getBlockState, breakNaturally, ...) |
| FS062 | warning | region-guarded BlockState calls (update, getDrops, randomTick) |
| FS063 | warning | any org.bukkit.entity call from an off-region context |
| FS064 | warning | global-region-guarded World calls (setTime, setStorm, setGameRule, setChunkForceLoaded, setMetadata, ...) |
| FS065 | warning | region-guarded Chunk (getEntities, getTileEntities, getBlock, load) and World entity-query / rayTrace / spawn calls |
| FS070 | warning | direct net.minecraft / org.bukkit.craftbukkit access, one finding per class |
| FS080 | info | isPrimaryThread() used as a safety gate |
| FS081 | warning | unsynchronized static HashMap / ArrayList / HashSet mutated inside concurrent Folia region or async tasks |
| FS082 | warning | cross-region passenger attachment or vehicle ejection (addPassenger, removePassenger, eject, leaveVehicle) off-region |
| FS083 | warning | EntityScheduler#runDelayed / runAtFixedRate submitted with null retired callback |
| FS084 | warning | unchained Entity#teleportAsync discarding CompletableFuture before subsequent entity access |
| FS085 | warning | Bukkit.getOnlinePlayers() iterated from an off-region context without per-player EntityScheduler dispatch |
| FS086 | warning | synchronous cross-region HumanEntity#openInventory / container access off-region |
| FS087 | warning | blocking join() / get() / resultNow() on World#getChunkAtAsync* or Entity#teleportAsync region-completed futures |
| FS088 | warning | live World cast or lookup inside Moonrise parallel async ChunkGenerator or BlockPopulator worker callbacks |
| FS089 | warning | TileState, Container, or Paper 26.3 block-entity (Chest, Sign, TrialSpawner, Vault, Crafter, ...) accessed off-region |
| FS090 | warning | pre-fetched BlockState or TileState snapshot captured across delayed RegionScheduler ticks or EntityScheduler callbacks |
| FS091 | warning | PersistentDataContainer mutation (set, remove, readFromBytes, copyTo) from off-region or async context |
| FS092 | warning | Structure#place multi-block template paste across potentially unbounded regional chunk boundaries |
| FS093 | warning | Bukkit.createInventory with world-bound TileState or Entity holder off-region |
| FS094 | warning | BossBar player list mutation (addPlayer, removePlayer, removeAll) off global region |
| FS095 | warning | WorldBorder configuration mutation (setCenter, setSize, ...) from regional tick thread |
| FS096 | warning | MapView renderer or world configuration mutated off global region |
| FS097 | warning | Bukkit.broadcastMessage / Server#broadcast called from regional or async context |
| FS098 | warning | ServicesManager#register / unregister / unregisterAll mutated asynchronously |
| FS099 | warning | PluginManager#registerEvents / unregisterEvents / unregisterAll mutated off global tick |
| FS100 | warning | BlockData state setters invoked from async context before Block#setBlockData |
| FS101 | warning | unconfined Kotlin coroutine DelayKt#delay / Dispatchers.Unconfined suspension or off-region Continuation#resumeWith |
| FS102 | warning | Bukkit.selectEntities / Server#selectEntities vanilla target selector evaluated off-region |
| FS103 | warning | Inventory, PlayerInventory, or EntityEquipment slot mutation off-region |
| FS104 | critical | runtime Bukkit.reload / Bukkit.reloadData (UnsupportedOperationException on Folia) |
| FS105 | warning | unsynchronized instance HashMap / ArrayList / HashSet field mutated across concurrent Folia tasks |
| FS106 | warning | Entity / Player captured into Location-keyed RegionScheduler closure and mutated without isOwnedByCurrentRegion |
| FS107 | warning | live Chunk instance captured across RegionScheduler#runDelayed / runAtFixedRate or EntityScheduler closure |
| FS108 | warning | Scoreboard Team, Objective, or Score state mutated off global region |
| FS109 | warning | AdvancementProgress#awardCriteria / revokeCriteria mutated off-region |
| FS110 | warning | LootTable#fillInventory / populateLoot evaluated off-region |
Severities mean specific things:
- blocker - the plugin will not load at all.
- critical - Folia throws whenever the code runs, on any thread. Reported unconditionally, unless the code is behind a Folia guard, in which case it drops to info.
- warning - legal from the region that owns the data, fatal from anywhere else. Only reported when the call sits in a context FoliaScan can show is off-region.
- info - behaviour differs enough to need a human decision.
FS070 is deliberately counted per class rather than per call site. An NMS adapter or model engine touches server internals thousands of times by design, and enumerating each one buries every other finding, so the finding carries the distinct type count instead.
- Parse every class with ASM. Nothing is loaded or executed, and no bytecode is written.
- Read
paper-plugin.yml/plugin.ymlfor the descriptor, then work out the plugin's own package(s).mainalone is not enough - plugins commonly park the entry class in a platform subpackage (dev.aurelium.auraskills.bukkit.AuraSkills) while most of the code lives in sibling packages, and forks often keep the legacymainpackage for addon compatibility while placing new code under<tld>.<author>.<PluginName>(e.g.GravesXkeepingcom.ranull.graves.Gravesalongsidedev.cwhead.GravesX). FoliaScan widensmain's root and includes packages matching the descriptor's plugin name. The report prints the roots it chose and how many of the jar's classes they cover. - Find off-region entry points: a lambda or
Runnablehanded to an executor, aCompletableFutureasync stage (plus non-asyncthenAccept/thenApply/thenRuncontinuations chained ontosupplyAsyncorrunAsync, while sparing Folia-safe futures likeEntity#teleportAsync), a rawThread,java.util.Timer,runTask*Asynchronously, Paper'sAsyncScheduler, a Bukkit/Paper async event handler (AsyncPlayerChatEvent,AsyncChatEvent,AsyncPlayerPreLoginEvent,AsyncPlayerConnectionConfigureEvent), a ProtocolLib / PacketEvents / Netty channel packet callback running on Netty I/O threads, or aGlobalRegionSchedulercallback (region={null}, which owns global server/world stateFS050/FS064but owns no chunks, blocks, or entitiesFS060throughFS063andFS065). - Propagate that breadth-first across in-jar call edges, recording every call-site hop and
bytecode line number so helpers called from async tasks carry the complete regional taint call
chain (emitted in human messages and SARIF
codeFlows/threadFlows). Callbacks inside an async method that hop back ontoEntitySchedulerorRegionSchedulerare recognised as regional re-entries and do not inherit off-region taint. - Find the Folia guards, so the correct non-Folia branch of a dual-platform plugin is not reported as a defect (below).
- Apply the rule table, keeping one finding per source line.
A plugin that supports both servers has to contain legacy calls, and they are correct precisely because they never run on Folia. FoliaScan looks for the guard and downgrades a critical finding to info when it finds one, naming the guard instead of muting the finding. Both shapes real plugins use are recognised:
// per method - one class, one flag, a branch in every method
fun runGlobal(task: Runnable) =
if (isFolia) Bukkit.getGlobalRegionScheduler().run(plugin) { task.run() }
else Bukkit.getScheduler().runTask(plugin, task)
// per class - one interface, two implementations, chosen once at startup
val scheduler = if (IS_FOLIA) PaperScheduler() else BukkitScheduler()A method qualifies when it both tests for Folia and contains a region-scheduler call; the second
half is what stops this from muting everything, since unconditional legacy code has no region call
to pair with the test. FoliaScan recognises folia flags, ServerBuildInfo#isBrandCompatible, and
PaperMC's canonical Class.forName("io.papermc.paper.threadedregions.RegionizedServer") probe even
when stored in a neutrally named static boolean (HAS_REGIONS) or helper (supportsRegions()). A
class qualifies when every new of it sits in a method that tests for
Folia - and the test has to be independent of the class itself, or anything named FoliaScheduler
would vacuously guard itself. Lambdas created inside a guarded method inherit the guard, because a
task built in the legacy branch compiles into its own synthetic method.
Two limits, stated rather than hidden: a class built reflectively or by a DI container has no
visible new, so it stays reported; and there is no control-flow analysis, so a method that tests
for Folia and also calls the legacy scheduler outside the branch is treated as guarded. The first
errs toward reporting, the second away from it.
FoliaLib is the case that defeats both shapes, and it is worth knowing about because it is the
library most Folia-targeting plugins reach for. Its factory does
Class.forName(basePackage + implName), so nothing ever writes new SpigotImplementation() and no
method of that class tests for Folia - the test lives in the factory, one indirection away, keyed by
a string. What is still visible is the shape: a class this jar never constructs, sitting next to a
sibling implementation of the same interface that does use the region API. That earns an explanation
naming the sibling, and no change in severity - it is suggestive, not proof, and a wrong
all-clear costs more than a wrong warning.
Relocated dependencies are analysed but not blamed. A compatibility shim like FoliaLib
deliberately contains a legacy BukkitScheduler implementation for non-Folia servers, so
reporting it is noise; the code still counts toward "Folia API usage" and still taints the plugin
code it calls. Two signals identify it: build-tool folder names (libs, shaded, vendor, ...)
and a curated list of library leaf names, because relocation often leaves no marker folder at all
(dev.aurelium.auraskills.kyori). That list is necessarily incomplete, so every subtree it
matches is named in the report notes, --exclude adds your own, and --all turns it off.
Only segments below the plugin's own root count, and a jar with no plugin descriptor is never
filtered at all - otherwise pointing the scanner at one of those libraries directly would
exonerate the whole jar. Scanning IF-0.12.0.jar should report the two
Bukkit.getScheduler().runTask calls in its GuiListener, not "no findings" just because
inventoryframework is a name plugins shade. The same rule is what keeps MythicLib's own
io.lumine.mythic.lib from reading as a relocation folder because it ends in lib.
A name match is also skipped when the segment before it says "adapter": plugins name their own
integration packages after the library they integrate with, so comp.protocollib and
hooks.placeholderapi are the plugin's code, not a copy of the library. The search continues
past it, so a library genuinely relocated deeper (compat/libs/kyori/...) is still found.
Every entry on the name list has to be a library identity rather than a domain noun, for the
same reason. Measured over eleven real plugin jars plus a Prometheus exporter, nbt,
annotations, mysql, sqlite and metrics only ever matched plugins' own packages and were
removed - metrics hid all four critical findings in an exporter whose entire job is metrics,
including a scheduleSyncRepeatingTask call. internal and external went too: no build tool
generates either, and plugins use both constantly. Deleting the list wholesale is not the answer
either, since one jar that relocates without any marker folder (dev.aurelium.auraskills.acf,
.kyori) then produces 74 findings on clean code.
FoliaScan reports; it does not modify your jar.
FoliaPhantom / pasta (MIT) rewrites plugin bytecode to
route legacy scheduler calls through its own shim. Different job, and useful if you want a server
to boot today. Two things to know if you use it: PluginPatcher#modifyPluginDescriptor appends
folia-supported: true unconditionally, without analysing whether the result is region-safe, and
its own README disclaims thread-safety guarantees. So a patched jar's declared flag is a machine's
assumption, not the author's claim - which is what rule FS002 exists to surface. FoliaScan
detects the runtime classes pasta bundles and says so instead of trusting the flag.
folia-checker (MIT) is a VS Code
extension applying line-by-line regular expressions to .java sources. Source-only, Java-only,
and regex granularity means it cannot separate runTaskAsynchronously from runTask without
hand-tuned patterns.
FoliaLib and similar are runtime helper libraries: they help you write Folia-compatible code. FoliaScan tells you whether you already did. They compose - a jar bundling FoliaLib scans clean, because relocated shim code is analysed but not blamed.
Worth reading before treating a clean run as a guarantee.
- A clean result is not a proof of correctness. It means none of the enabled rules matched.
- Calls leaving the jar are not followed. If an async entry point lives in a dependency and calls back into your code by interface, the taint can be missed.
- Reflection, injected executors and thread pools obtained from other plugins are invisible.
- A helper used from both sync and async callers is reported. That is intentional - it genuinely may run off-region - but it is not always a bug.
--fail-on criticalonly judges unconditional failures. Region-guarded misuse that FoliaScan cannot place in an off-region context will not appear at all.- Findings need line numbers to be actionable; a jar stripped of debug info still gets class and method attribution, but no lines.
Every rule cites a file and member inside Folia's own patch set, printed with each finding and
listed by foliascan --rules. The dataset behind the table was extracted mechanically, not
recalled: tools/extract_folia_throws.py walks a Folia checkout and reports every added
throw new UnsupportedOperationException, every TickThread.ensureTickThread guard, and the
@Deprecated marker on BukkitScheduler.
git clone --depth 1 https://github.com/PaperMC/Folia.git /tmp/folia
python tools/extract_folia_throws.py /tmp/foliaRe-run it when Folia changes to check the table is still accurate. Rules were verified against Folia at the 1.21.11 branch state on 2026-08-22.
No Folia or Paper source is vendored, copied or redistributed here. The rule table references class and member names and quotes short diagnostic strings so that each claim can be audited.
FoliaScan is an independent tool and is not affiliated with or endorsed by PaperMC.
FoliaScan is part of a focused static-analysis, staging, resource-pack, and coding-agent suite by SalyVn:
| Project | Role |
|---|---|
| minecraftkit | Offline RPG and Paper/Folia API catalog, 10 /mc:* skills for Claude Code and Codex, web API explorer, and stdio MCP server |
| serverdoctor | Offline server diagnostics across logs, configs, JVM flags, plugin sets, worlds, crash reports, and access lists (CLI + MCP) |
| pluginscope | Static audits for plugin JAR packaging, shading/relocation, Paper API version compatibility, plugin stacks, and resource packs (CLI + MCP) |
| mcstage | Standalone integration harness that boots real Paper, Folia, and Purpur servers, drives console commands, and asserts on logs |
| glyphsmith | Deterministic Minecraft font glyph packer solving ascent, padding, advance, and negative-space shifts into a resource pack |
New rules need a provenance entry pointing at the Folia source that justifies them, plus a
fixture in src/test/kotlin/fixtures/ proving both that the rule fires on bad code and that it
stays quiet on the region-aware equivalent. Rules without evidence will not be merged - the
value of this tool is that its output can be checked.
./gradlew testApache-2.0. See NOTICE for third-party attributions.