Troubleshooting

Troubleshooting

Start here first:

./gradlew hytaleDoctor

hytaleDoctor prints a summary of:

• configured hytaleVersion and patchline
• manifest path and run directory
• resolved asset wrapper path and effective Assets.zip path (local override path when hytaleHomeOverride is set, otherwise the Gradle cache path
• auth token cache path
• resolved vineServerJar files
• declared vineImplementation, vineCompileOnly, and vineDecompileTargets dependencies

Use it when:

• runServer fails
• assets are missing
• manifest values look wrong
• expected dependency sources are not showing up

Missing hytaleVersion

If hytaleVersion is not set and no vineServerJar is declared, tasks that require the server jar may fail.

Always configure:

hytaleTools {
  hytaleVersion = '...'
}

Dynamic version not resolving the expected build

If you're using a dynamic selector like 0.+ and Gradle is picking the wrong version (or claims it can't find any matching version), check the following:

• Use +, not *. Gradle's dynamic version syntax is 0.+, not 0.*. The * form is treated as a literal version string and will fail to resolve.
• Confirm patchline is set correctly. Dynamic resolution is scoped to the active patchline. If you're tracking pre-release builds, set patchline = 'pre-release' (or hytale_patchline=pre-release in gradle.properties).
• Force a refresh. Dynamic versions are cached for 10 minutes. Run ./gradlew --refresh-dependencies to bypass the cache and refetch the latest version listing.
• Check hytaleDoctor. The diagnostic task prints the configured patchline and the resolved server jar files so you can confirm what was actually picked.

Sources are not attached in the IDE

Run:

./gradlew prepareDecompiledSourcesForIde

This allows IDEs to attach readable generated source code instead of showing only compiled classes.

Then refresh or reimport the Gradle project in your IDE.

Also verify the dependency is listed in vineDecompileTargets if you expect decompiled dependency sources.

Hytale API comments are not showing in generated server sources

The plugin injects hosted Hytale API docs into generated server sources during prepareDecompiledSourcesForIde. If source comments are missing:

1. Confirm injectServerJavadocsIntoSources is not disabled.
2. Confirm serverJavadocsUrl points at the correct release or pre-release docs site.
3. Delete the generated source jars and Javadoc cache, then regenerate sources.

rm -rf build/vineflower/hytale-server
rm -rf build/generated-sources-jars/server
rm -rf build/generated-sources-m2
rm -rf build/generated-sources-ivy
rm -rf ~/.gradle/caches/hytale-javadocs/release
./gradlew prepareDecompiledSourcesForIde --rerun-tasks

The injector only adds comments where a matching hosted Javadoc page and member documentation can be found.

runServer fails because assets are missing

Run:

./gradlew downloadAssetsZip

Also verify:

• hytale_version is set correctly
• hytale_patchline matches the artifact you expect
• authentication cache under Gradle user home is valid

manifest.json is out of date

Run:

./gradlew updatePluginManifest

The build also wires manifest validation automatically, so this usually indicates missing configuration values.

Manifest validation fails during build

Verify the configured values for:

• manifestGroup
• modId
• mainClass
• hytaleVersion

Also review:

• manifest_dependencies
• manifest_opt_dependencies
• includes_pack
• Authors, if present, must be an array of objects with a non-blank Name; optional Email and Url values must not be blank

Dependency sources are not being generated

Make sure the dependency is declared in:

vineDecompileTargets "group:module:version"

Only dependencies in that configuration are decompiled for IDE attachment.

preRunTask does not run

Verify that:

• the task name matches exactly
• the task is registered in the same project as runServer
• preRunTask is set to the task name as a string

Validate your debug / hot swap runtime

Run:

./gradlew hytaleJvmDoctor

Use it to verify:

• which Java executable runServer will use
• whether JetBrains Runtime was detected
• whether enhanced class redefinition is supported
• whether bundled HotswapAgent support is available

If hot swap is not working as expected, this should be the first check.

External HotswapAgent jar is not found

If hotswapAgentPath or hytools.hotswap.agent.path is set, the file must exist and point directly to a HotswapAgent jar.

Example:

hytaleTools {
    hotSwapEnabled = true
    useHotswapAgent = true
    hotswapAgentPath = '/absolute/path/to/hotswap-agent.jar'
}

Or:

hytools.hotswap.agent.path=/absolute/path/to/hotswap-agent.jar

If the file does not exist, runServer fails early with a clear error instead of launching without the agent.

Duplicate JDWP debugger agent

If you launch runServer from IntelliJ using Debug, IntelliJ may inject its own JDWP debugger agent.

The plugin checks for an existing JDWP argument before adding its own debug agent. This prevents JVM startup errors such as:

Cannot load this JVM TI agent twice, check your java command line for duplicate jdwp options.

For command-line debugging, use:

./gradlew runServer -Ddebug=true

For IntelliJ debugging, using the IDE's Debug action is usually enough. Avoid manually adding another -agentlib:jdwp=... entry in serverJvmArgs unless you know IntelliJ is not already providing one.

---

Home | Task Reference | Troubleshooting