core-network/docs/wiki/Troubleshooting.md

Troubleshooting

NetworkPlugin has not been configured

No startup source produced both a control-plane base URL and token before another plugin requested NetworkPlugin.client().

Fix with one of:

• environment variables: KWB_CONTROL_PLANE_BASE_URL and KWB_CONTROL_PLANE_TOKEN
• JVM properties: kweebec.controlPlane.baseUrl and kweebec.controlPlane.token
• local plugin config: control-plane.json
• explicit startup call: NetworkPlugin.configure(baseUrl, token)

Check which source configured the client:

NetworkPlugin.configurationSource();

Optional.empty() means no source configured the shared client.

Startup Config Precedence

Startup values are resolved in this order:

1. environment variables
2. JVM system properties
3. control-plane.json

Environment variables and JVM properties override only the fields they set. Missing fields can still come from a lower-priority source.

Config File Token Warning

control-plane.json is a short-term local deployment fallback. Prefer environment variables for production or control-plane-provisioned servers.

JVM -D properties are supported, but some host tooling can expose process arguments. Avoid logging launcher commands that contain tokens.

Auth Failures

AuthException maps to HTTP 401 or 403.

Common causes:

• missing token
• expired or invalid token
• inactive service account
• token missing required ability
• server-instance token trying to access a different instance route

Batch Futures Never Complete

Likely causes:

• batching scheduler has not started
• NetworkPlugin is not loaded as the plugin main class
• code enqueued calls but never called batch().flush() in tests
• control plane does not expose /api/v1/batch

In tests, call:

client.batch().flush();

Cached Reads Keep Returning Stale Data

This can be expected behavior. If a refresh fails and an old value exists, cache APIs return the stale value and increment failed sync metadata.

Check:

cache.metadata(call, context)

Look at:

• failedSyncCount
• lastError
• syncState

PLAYER cache calls require PlayerCacheContext

Player storage is explicit. Use:

new PlayerCacheContext(playerId, playerRef, entityStore)

Core-network will not infer player identity from /players/{player} URIs.

NetworkApiDataComponent has not been registered

The player cache component is registered in NetworkPlugin.setup().

This error usually means:

• tests are using player storage without plugin setup
• NetworkPlugin is not the active Hytale plugin main class
• code is accessing player cache before component registration

Asset Store Cache Does Nothing

ASSET_STORE storage requires a plugin-provided AssetStoreCacheAdapter.

Core-network does not create a generic Hytale asset store because Hytale assets require concrete asset classes, codecs, keys, and load/write behavior.

Manifest Rewrites During Gradle Tasks

processResources depends on updatePluginManifest, which rewrites src/main/resources/manifest.json from Gradle properties.

If the manifest changes unexpectedly after tests/builds, check:

• includes_pack in gradle.properties
• version in gradle.properties

Avoid committing unrelated manifest churn.