Build & Test Troubleshooting FAQ

Build & Test Troubleshooting FAQ

Purpose: Reference guide for diagnosing and resolving build failures, test failures, and other development environment issues.

When to use: When encountering unexpected build or test failures, especially those that seem environment-related rather than code-related.

---

FAQ

Q1: NeoForge GameTest fails with "Illegal version number specified version (main)"

Symptoms:

File /​path/​to/​neoforge-1.21.2/​build/​resources/​main is not a valid mod file
Caused by: java.lang.IllegalArgumentException: Illegal version number specified version (main)

Cause: IDE (IntelliJ IDEA, Eclipse) generated bin/ directories containing unprocessed resource files. The neoforge.mods.toml in bin/​main/​META-INF/ has version="${version}" instead of the actual version number.

Solution:

1. Delete IDE-generated bin directories:

   rm -rf neoforge-1.21.2/​bin common-1.21.2/​bin
   

2. Or run the cleanAll task which now includes bin/ cleanup:

   ./​gradlew cleanAll
   

Prevention:

• Configure IDE to use Gradle for builds instead of built-in compiler
• Add bin/ to .gitignore (already done in this project)

Reference: Discovered 2026-01-25 during portal GameTest implementation.

---

Q2: GameTest structure template not found or too small

Symptoms:

• Tests fail with "structure not found" errors
• Portal/​structure tests fail because test area is too small

Cause:

• Fabric uses FabricGameTest.EMPTY_STRUCTURE constant (built-in)
• NeoForge requires explicit structure template files

Solution: For NeoForge, create a proper NBT structure file:

1. Create empty_test.nbt in common-{version}/​src/​main/​resources/​data/​chronodawn/​structure/
2. Reference it as "chronodawn:empty_test" in test configuration

Note: The structure must be large enough for the test content (e.g., 10x10x10 for portal frame tests).

---

Q3: Gradle daemon conflicts during parallel builds

Symptoms:

• Build fails with lock file errors
• "Could not create service of type" errors
• Tests hang or fail intermittently

Solution:

./​gradlew --stop
./​gradlew cleanAll

---

Q4: Test passes on Fabric but fails on NeoForge (or vice versa)

Checklist:

1. Mixin configurations: Check both loader-specific mixin JSON files
2. Structure templates: NeoForge needs explicit templates, Fabric has EMPTY_STRUCTURE
3. API differences: Some APIs behave differently between loaders
4. IDE artifacts: Run ./​gradlew cleanAll to remove stale bin/ directories

---

Q5: "session.lock" errors during GameTest

Symptoms:

Failed to lock the level ... session.lock

Cause: Previous test run left a lock file.

Solution: The gameTestAll task already handles this by cleaning stale world directories. If it persists:

rm -rf fabric-*/​run/​gametestworld
rm -rf neoforge-*/​run/​gametestworld

---

Adding New FAQ Entries

When encountering a new build/​test issue:

1. Document symptoms (exact error message)
2. Identify root cause
3. Document solution
4. Add prevention tips if applicable
5. Add reference date for tracking