# 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:

```java
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:

```java
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:

```java
cache.metadata(call, context)
```

Look at:

- `failedSyncCount`
- `lastError`
- `syncState`

## `PLAYER cache calls require PlayerCacheContext`

Player storage is explicit. Use:

```java
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.