World Dimension Loader 1.4.1-beta3 - Troubleshooting (Public Beta Candidate)

Workbench does not open
- Confirm Creative mode and permission level 2 or higher.
- The Workbench has no survival recipe; obtain it from the WDL Creative tab.

Save says the data changed or is stale
- Use Refresh and retry from the current server state.
- Do not force an older edit over newer Config.

The Dimension Delete button is missing
- This is expected in 1.4.1-beta3. Dimension definition deletion is not available from the Workbench.
- Gate definition deletion remains available.

Workbench Config changes are locked
- First run `/wdl pending-delete status`. This can happen when a beta1-originated Dimension-delete plan still exists.
- While that inherited recovery state exists, WDL can temporarily block other Workbench Config changes so the saved recovery checks are not invalidated.
- Prefer a safe restart/finalization path. Use `/wdl pending-delete cancel` only when you intentionally want to remove that existing pending plan.

A beta1 pending Dimension deletion will not finalize
- Stop further Config changes and preserve latest.log/debug.log. Make a backup/test copy before recovery.
- Run `/wdl pending-delete status`. If the saved checks no longer match current Config, WDL stops instead of guessing or rebasing automatically.
- Do not manually delete the pending-plan file, transaction files, WDL runtime folders or configured source-world folders to force recovery.
- Physical WDL world data and configured source-world data must remain untouched by this Config-definition recovery path.

See WDL_GUI_GUIDE_EN_1.4.1-beta3.txt and WDL_COMMAND_GUIDE_EN_1.4.1-beta3.txt.

============================================================
Additional established troubleshooting
============================================================
============================================================
1. Imported world is not READY
============================================================
Check:
/wdl scan
/wdl list
/wdl status

Confirm:
- WDL_custom_dimensions/<id>/level.dat exists
- no accidental double folder
- dimensions.toml id is a bare WDL path such as test_world_01
- do not use worlddimensionloader:test_world_01 as the definition id
- source world is a copy and is readable

Malformed or namespaced definition IDs are rejected early.

============================================================
2. Gate does not activate
============================================================
Check:
- destination is READY
- frame/corner/size matches the definition
- allowed Igniter rules match
- selection_mode/dimensions is valid
- policy, Timed Session, cooldown, or Reset state is not sealing entry

For the minimal Gate:
[[gates]]
id = "test_world_01_gate"
dimensions = ["test_world_01"]

This infers LIST.

============================================================
3. Multiple Gates stopped working
============================================================
WDL rejects physically ambiguous Gate definitions fail-closed.

Two definitions can be ambiguous when they overlap in:
- frame block
- corner block
- size range
- applicable Igniters

Destination IDs do not distinguish the physical Gate.

Fix by changing frame/corner blocks, using non-overlapping size ranges, or different Igniter restrictions.

============================================================
4. Gate now selects only the listed Dimension
============================================================
When selection_mode is omitted and dimensions is non-empty, WDL resolves the Gate to LIST mode.

Older Config may have relied on historical omitted-mode ALL behavior.
If you intended ALL, add:
selection_mode = "ALL"

If both mode and dimensions are omitted, legacy ALL fallback remains.

============================================================
5. ALL does not send me to Overworld
============================================================
This is expected. ALL means eligible READY WDL imported Dimensions only.

Use:
selection_mode = "LIST"
dimensions = ["minecraft:overworld"]

Do not mix Overworld and WDL IDs in one LIST.

============================================================
6. Reset seems to use huge disk space
============================================================
With the safe default:
defer_dimension_cleanup_until_restart = true

retired physical generations remain until the next game/server startup.
Repeated Reset before restart can temporarily multiply runtime world storage.

Restart so Startup GC can remove proved-safe retired generations.

Do not manually delete live runtime folders while the game/server is running.

============================================================
7. My builds/changes disappeared after Reset
============================================================
This is expected for resettable Dimensions.

Reset builds the next runtime generation from the imported source copy. Changes made while playing in the runtime Dimension can be discarded.

The imported source copy under WDL_custom_dimensions remains untouched.

If you need persistent player-built changes, do not enable reset_on_empty for that Dimension unless another preservation mechanism is used.

============================================================
8. I enabled live cleanup
============================================================
defer_dimension_cleanup_until_restart = false allows WDL to attempt live unload/delete.

This mode is not recommended. Other mods may keep Dimension references and cause Reset failure, crash, or data inconsistency.

If Valkyrien Skies is detected, WDL ignores live-cleanup intent and forces deferred cleanup.

============================================================
9. WDL_backups remains after backup=false
============================================================
Expected.

resident_gc_backup = false means WDL does not create/update a new Resident GC backup.
It does not delete an existing archive.

Backup path:
WDL_backups/resident_gc/<save-id>/latest.zip

Remove an old archive manually only when you are certain you no longer need it and the game/server is stopped.

============================================================
10. /wdl scan did not apply my change
============================================================
Some settings are STARTUP ONLY.

A full restart is required for startup-latched cleanup/retired-generation behavior and Advanced Dimension Igniter durability.

============================================================
11. Reset becomes FAILED_BLOCKED
============================================================
Do not force-delete runtime folders.

Use:
/wdl status
/wdl loaded
/wdl probe <id>

Save latest.log/debug.log. FAILED_BLOCKED is a fail-closed safety state and the blocking authority/reference must be diagnosed.

============================================================
12. Valkyrien Skies / Distant Horizons
============================================================
Valkyrien Skies (VS) and Distant Horizons (DH) are both optional.
WDL works with neither installed.

Current safety behavior was validated mainly around Valkyrien Skies 2.4.11 and DH 3.2.0-b.
Unknown future versions are not guaranteed.
VS detection forces deferred cleanup.

============================================================
13. Existing Config comments look old
============================================================
WDL never overwrites existing Config files.

To obtain current comments:
1) back up config/worlddimensionloader/
2) move old files aside
3) start once to regenerate
4) merge only intentional overrides
============================================================
14. Reset is OFF but the runtime still uses a timestamp path
============================================================
This is normal when a timestamp generation is already current from 1.3.0 or another earlier run.

The fixed-ID rule applies when a new/pristine runtime is initialized with reset_on_empty=false.

Disabling Reset on an existing timestamp current runtime:
- does not reverse-migrate it;
- does not rename its folder;
- preserves existing current authority.

Do not manually move/rename an existing runtime between fixed, timestamp, or legacy-canonical layouts.

============================================================
15. Startup is BLOCKED because runtime authority is ambiguous
============================================================
If exact lifecycle authority is unavailable and multiple physical candidates exist for one logical ID, WDL 1.4.1-beta3 stops fail-closed.

Example:
dimensions/wdl/test_world_01/                 # fixed payload
dimensions/wdl/test_world_01/<timestamp>/     # timestamp generation

The legacy canonical path `dimensions/worlddimensionloader/test_world_01/` is also a competing authority if it exists at the same time.

WDL does not:
- guess which candidate is current;
- silently allocate a replacement generation;
- move folders;
- delete candidates;
- let Startup GC delete candidates whose current/retired status cannot be proven.

Action:
1) stop the game/server;
2) back up the complete save;
3) preserve latest.log/debug.log;
4) preserve /wdl status and /wdl probe output if available;
5) do not manually delete runtime folders while diagnosing.

============================================================
16. I changed reset_on_empty=false but Reset continues
============================================================
A Config change may cancel Reset before destructive authority exists.

After same-operation destructive/recovery authority exists, WDL does not simply cancel the transaction.
Recovery/transaction safety takes precedence over the Config change.

Malformed/conflicting Journal or recovery authority is also not treated as "nothing happened"; WDL fails closed.

Do not force-unblock this by deleting runtime folders.

============================================================
17. What do RESET DEFERRED and RESET BLOCKED mean?
============================================================
`WDL RESET DEFERRED` at INFO is normally a non-terminal wait/retry indicator. Examples include a timed session still being present or Resident Reset waiting for a restart-safe condition. WDL dedupes the same reason within the same logical Dimension + operation + phase, so alternating routine reasons should not create a log storm.

A different reason may appear once in the same scope. The same reason may appear again after the Reset advances to a new phase or a new Reset operation begins.

`WDL RESET BLOCKED` at ERROR is different: it is terminal fail-closed safety handling. Preserve latest.log/debug.log and backups, and investigate the reason. Do not delete runtime folders, Journals, Rotation Receipts, or quarantine data to force recovery.
