Troubleshooting

Validation and error handling

At server startup, Advancement Portals parses the config and validates the resulting gates.

Invalid resource IDs

An invalid dimension or advancement ID is logged and skipped.

Example of an invalid ID:

Minecraft The End

Correct form:

minecraft:the_end

Invalid mode

Only ALL and ANY are valid.

Invalid:

"minecraft:the_end | BOTH | minecraft:end/kill_dragon"

Valid:

"minecraft:the_end | ALL | minecraft:end/kill_dragon"

Mode parsing is case-insensitive, but uppercase is recommended.

Empty requirement list

A gate with no valid advancement IDs is ignored.

Invalid:

"minecraft:the_end | ALL | "

Unknown advancement

A syntactically valid but unloaded advancement is retained as a requirement and remains incomplete.

This is intentional. A typo should not silently open a protected dimension.

Correct the ID or restore the mod/datapack that provides it.

Missing dimension

A gate targeting a dimension that is not currently loaded is reported as a warning.

The gate can still remain in the parsed config. This is useful when a dependency or datapack is temporarily missing, but it should be corrected before release.

Validation summary

The startup log reports:

• Number of loaded gates.
• Number of unique advancement requirements.
• Number of detected issues.

Always review this summary after editing the config or changing modpack versions.

Troubleshooting

The portal blocks me but does not show a message

Check:

• enabled = true.
• The player is not seeing a client chat filter issue.
• warningCooldownSeconds is not causing a recent warning to be suppressed.
• The correct version of the mod is installed.
• The server log does not show an exception.
• The attempted destination is the dimension you think it is.

Version 3.1 fixes a previous warning-order bug that could cancel travel before displaying the explanation.

The portal does not block an operator

By default:

operatorsBypassGates = true
operatorBypassPermissionLevel = 2

Disable operator bypass while testing:

operatorsBypassGates = false

Also check Creative and Spectator bypass settings.

The portal never unlocks

Check the server log for an unknown advancement.

Confirm:

• The advancement ID is correct.
• The advancement exists on the server.
• The advancement is fully complete, not partially progressed.
• The gate uses the intended ALL or ANY mode.
• The destination has only one final gate entry.
• The providing mod or datapack loaded successfully.

A syntactically valid but missing advancement intentionally remains blocking.

One of my duplicate gates is ignored

The final valid entry for a destination replaces earlier entries.

Combine the requirements into one gate.

An ANY gate acts like ALL

Confirm the entry has three pipe-separated sections:

"minecraft:the_end | ANY | advancement:a, advancement:b"

Legacy dimension=[...] entries are always ALL.

Team sharing does not work

Confirm:

• FTB Teams is installed on the server.
• Both players are members of the same FTB Teams party.
• shareAdvancementsWithTeam = true.
• The advancement passes the portal-only and recipe filters.
• The target player does not already have the advancement.
• The FTB Teams version matches the expected Forge 1.20.1 API.
• The server log says the FTB Teams integration is ready.
• Login synchronization is enabled for offline testing.

Only portal advancements are sharing

Check:

shareOnlyPortalAdvancements = true

Set it to false to share other eligible newly earned advancements.

Recipe advancements are not sharing

This is the default:

shareRecipeAdvancements = false

Set it to true to share recipe advancements.

A recipe advancement explicitly used as a portal requirement remains shareable even while the option is false.

An offline teammate did not receive an old advancement

Offline storage records progress earned while the sharing system is active.

For progress earned before 3.1, the mod discovers configured portal requirements from online teammates. It does not reconstruct every historical non-portal advancement.

Have a teammate with the portal advancement join, then allow login or portal synchronization to run.

A shared advancement gave extra rewards

That is expected Minecraft behavior. The mod completes the normal advancement criteria.

Use dedicated reward-free progression advancements or restrict sharing to portal advancements.

A player changed teams and brought progress with them

Shared history is stored by player UUID and merged according to current team membership during synchronization.

Strict team-isolated history is not part of version 3.1.

The config looks correct, but a modded portal bypasses the gate

The travel method must fire Forge's normal EntityTravelToDimensionEvent for a server player.

A mod that moves players through a custom mechanism without that event may bypass this handler. Report the travel mod and exact method used so compatibility can be investigated.

The dimension name in the message is imperfect

Vanilla dimensions have special friendly names. Custom dimensions are formatted from the path of their ID.

Version 3.1 does not yet have per-gate custom display names.