docs(migration): fresh-world kubejs root-owned crash-loop + fix

On a fresh mc_data volume the minecraft service crash-loops with
"AccessDeniedException: /data/kubejs/config" (ConsoleJS.STARTUP null NPE):
Docker auto-creates the bind-mount parent /data/kubejs as root:root, but
the itzg container runs as uid 1000, so KubeJS can't create its writable
siblings (config/cache/generated/logs). Only bites fresh worlds — cochi's
aged volume predates the ro submounts and is already 1000-owned.

Fix (durable): chown 1000:1000 /data/kubejs once, then restart.

- plan/22-migration.md: Troubleshooting section with symptom + fix.
- migrate-import.sh: manual tail now flags it with the exact commands.

Hit + resolved during the cochi->oxps migration.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
oierandClaude Opus 4.8 committed 2026-07-23 02:38:13 +02:00
1 parent b9bcc13b73
commit 05a98efe57
2 files changed
+43

No files matched your search

+35
View File
@@ -153,6 +153,41 @@ cochi's copy. Rolling back to cochi then **silently loses** those new
accounts/skins. Safe for hours as a fallback; not for weeks. If you must roll
back after real use, re-export from oxps and re-import onto cochi first.
## Troubleshooting
### minecraft crash-loops on a fresh host: `AccessDeniedException: /data/kubejs/config`
Symptom (in `docker compose logs minecraft`), restarting every ~15s:
```
java.nio.file.AccessDeniedException: /data/kubejs/config
Caused by: NullPointerException: Cannot invoke "...ConsoleJS.error(...)"
because "dev.latvian.mods.kubejs.script.ConsoleJS.STARTUP" is null
```
**Cause.** The compose file bind-mounts the kubejs *source* subdirs read-only
(`server_scripts`, `startup_scripts`, `data`, `assets`). To place those mounts,
Docker auto-creates their parent `/data/kubejs` — and on a **fresh `mc_data`
volume** it creates it as **root:root**. The itzg container runs as **uid 1000**,
so KubeJS can't create its writable siblings (`config/`, `cache/`, `generated/`,
`logs/`) → init aborts → `ConsoleJS.STARTUP` stays null → NPE → exit 1.
This only bites a **fresh world** (migration, new host, wiped `mc_data`). On an
aged host like cochi `/data/kubejs` predates the ro submounts and is already
1000-owned, so it never surfaced there.
**Fix** — chown the dir to 1000 once (durable; survives restarts):
```bash
docker compose stop minecraft
docker run --rm -v <project>_mc_data:/data alpine chown 1000:1000 /data/kubejs
docker compose up -d minecraft
```
`<project>` is the checkout dir basename (e.g. `ulicraft-server`). Distinct from
the "don't mount the whole kubejs dir ro" gotcha in `plan/05-minecraft.md` — same
mod, different trigger (ownership of the auto-created parent, not a ro root).
## Re-running / testing
Everything is idempotent-ish and safe to rehearse: