Troubleshooting

Each entry follows the same pattern: symptom, likely cause, resolution, verification.

No greeting appears

1. Symptom: A player joins and no greeting is delivered.
2. Likely cause: enabled is false, the relevant pool is disabled/empty, the player left before delayTicks elapsed, or the JAR is missing.
3. Resolution: Run /joingreetings status. Confirm enabled, pool enabled flags, and message counts. Confirm only one Dynamic Join Greetings JAR is present.
4. Verification: Run /joingreetings simulate returning in-game and wait for the configured delay.

Configuration reload fails

1. Symptom: /joingreetings reload reports failure.
2. Likely cause: Invalid JSON, unsupported configVersion, empty serverName, out-of-range delayTicks, duplicate ids, invalid weights, or invalid formatting.
3. Resolution: Check the server console for the validation error. Fix the file. Remember the previous configuration remains active until a reload succeeds.
4. Verification: Reload again and confirm the success message, then run /joingreetings status.

Invalid JSON

1. Symptom: Reload fails immediately after an edit.
2. Likely cause: Trailing commas, missing quotes, or broken brackets.
3. Resolution: Validate the JSON in an editor, restore from backup if needed, then reload.
4. Verification: Successful /joingreetings reload.

Invalid formatting

1. Symptom: Reload fails with a formatting error for a specific message line.
2. Likely cause: Broken Simplified Text Format tags in lines.
3. Resolution: Fix or remove the offending line. See Formatting.
4. Verification: Reload succeeds and /joingreetings preview returning renders the fixed line.

A returning player receives a first-time greeting

1. Symptom: An established player gets a first-time message.
2. Likely cause: Their UUID is missing from players.json, or history was reset/rebuilt incorrectly.
3. Resolution: Confirm the UUID is present in <world>/dynamic-join-greetings/players.json while the server is stopped. Re-add it if needed.
4. Verification: Next join uses the returning pool.

A new player receives a returning greeting

1. Symptom: A brand-new player gets a returning message.
2. Likely cause: Their UUID was already imported from playerdata, or was previously recorded.
3. Resolution: Stop the server and remove that UUID from players.json if you intentionally want a first-time greeting.
4. Verification: Next join uses the first-time pool and re-adds the UUID.

Greetings are delayed

1. Symptom: Messages appear several seconds after join.
2. Likely cause: Expected delayTicks behavior. Default is 40 ticks (~2 seconds). Maximum is 1200.
3. Resolution: Lower delayTicks if you want faster delivery, then reload.
4. Verification: /joingreetings status shows the new delay; simulate once.

Broadcast behavior is unexpected

1. Symptom: The joining player does or does not see the message.
2. Likely cause: Audience misunderstanding.
3. Resolution: Remember PLAYER = joiner only, BROADCAST = everyone except joiner, BOTH = everyone including joiner.
4. Verification: Simulate with two online accounts and the target audience.

Duplicate mod versions

1. Symptom: Confusing behavior or duplicate class/mod load warnings.
2. Likely cause: Multiple Dynamic Join Greetings JARs in mods.
3. Resolution: Stop the server and leave only one JAR.
4. Verification: Restart and confirm a single mod entry in the startup log.

Missing Fabric API

1. Symptom: The server refuses to load the mod or dependency checks fail.
2. Likely cause: Fabric API is missing or too old.
3. Resolution: Install Fabric API 0.160.0+26.2 or newer.
4. Verification: Server starts and /joingreetings status works.

Incorrect Loader version

1. Symptom: Dependency failure mentioning Fabric Loader.
2. Likely cause: Loader older than 0.19.3.
3. Resolution: Upgrade Fabric Loader, then restart.
4. Verification: Startup succeeds without loader dependency errors.

Incorrect Java version

1. Symptom: The server fails because Java is too old.
2. Likely cause: Runtime below Java 25.
3. Resolution: Run the server on Java 25+.
4. Verification: java -version reports 25 or newer and the server starts.

Compatibility with other chat or message mods

1. Symptom: Greetings, previews, or simulations fail to appear when another message API is present.
2. Likely cause: Conflicting chat delivery stacks. 1.0.2+26.2 fixed a known failure with Fabric Essentials Message API by switching to native components via Placeholder API.
3. Resolution: Confirm you are on 1.0.4+26.2 or newer. Test with /joingreetings preview returning. Check both mods’ logs.
4. Verification: Preview and a real join both deliver messages.

Restoring the default configuration

1. Symptom: You want the packaged defaults again.
2. Likely cause: Customized config no longer desired.
3. Resolution: Stop the server, delete or rename config/dynamic-join-greetings.json, start the server.
4. Verification: Status shows 10 first-time and 50 returning messages.

Locating console errors

1. Symptom: Reloads or history recovery fail without an obvious in-game explanation.
2. Likely cause: Details are logged server-side.
3. Resolution: Search the console/log for dynamic-join-greetings.
4. Verification: The log line identifies the file, validation rule, or recovery action.