# Troubleshooting

# Troubleshooting

Solutions for common issues with the Info Hub.

## Installation Issues

### Plugin Not Loading

**Symptoms:**
- No log messages from plugin
- Commands not working

**Solutions:**

1. Check Java version (requires Java 25+):
   ```bash
   java -version
   ```

2. Verify JAR is in correct folder:
   ```
   mods/KyuubiSoftInfoHub-3.1.1.jar                      ✓
   mods/kyuubisoft_infohub/KyuubiSoftInfoHub-3.1.1.jar   ✗
   ```

3. Check for startup errors in server log

4. Ensure compatible Hytale server version (0.7.x)

### Configuration Files Not Generated

**Symptoms:**
- Config folder empty
- Missing files

**Solutions:**

1. Ensure plugin loaded successfully
2. Check write permissions on the `mods/` folder
3. Restart server (not just reload)
4. Check for disk space issues

---

## UI Issues

### Info Hub Not Opening

**Symptoms:**
- `/ksinfo` command does nothing
- No UI appears

**Solutions:**

1. Check that the player has `ks.info.user.use` (granted by default)
2. A file with broken JSON is kept, copied to `<file>.corrupt-<time>` and replaced by defaults in memory; the server log names it, and `/ksinfoadmin reload` lists it in chat
3. If you renamed the main command in `config.json`, restart the server
4. Check server logs for errors

### Sections Not Showing

**Symptoms:**
- Main menu is empty
- Some sections missing

**Solutions:**

1. Check section is enabled:
   ```json
   "sections": {
     "faq": {
       "enabled": true
     }
   }
   ```

2. Check permission requirement:
   ```json
   "sections": {
     "staff": {
       "permission": "infohub.staff"
     }
   }
   ```

3. Verify the section config file exists

4. A page that does not exist or may not be opened returns to Start with "not available"

### Quick Tiles Not Working

**Symptoms:**
- Clicking a tile does nothing
- Error in chat

**Solutions:**

1. Verify the command exists on the server and the player may use it (tiles run as the player unless `runAsConsole` is set)
2. Check the tile's own `permission`
3. Validate JSON syntax in `quickaccess.json`
4. A tile that was changed while the book was open does nothing until the book is reopened
5. Tiles beyond the limit of 10 rows of 4 per side are not shown; the admin window warns about it
6. A console tile cannot be saved: the admin needs `ks.core.admin.dialog.console`, see [Permissions](./permissions#quick-tiles-that-run-as-the-console)

---

## Command Issues

### Commands Not Listed

**Symptoms:**
- Command section is empty
- Some commands missing

**Solutions:**

1. Check settings in `commands/categories.json`:
   ```json
   "settings": {
     "showModCommandsOnly": true,
     "showDefaultCommands": false
   }
   ```

2. Verify plugin isn't in `blockedPlugins`

3. Check if command is in `hiddenCommands`

4. Try `groupBy: "plugin"` for automatic detection

### Command Execution Not Working

**Symptoms:**
- Execute button does nothing
- Error message appears

**Solutions:**

1. Check execution is enabled (otherwise only **To chat** is available):
   ```json
   "execution": {
     "enabled": true
   }
   ```

2. Check command isn't blocked:
   ```json
   "execution": {
     "blockedCommands": ["op", "stop"]
   }
   ```

3. Verify player has permission for the command

---

## Localization Issues

### Translations Not Loading

**Symptoms:**
- Shows English instead of selected language
- Shows raw keys like `infohub.book.nav.rules`

**Solutions:**

1. Check the player's language (`/kslang`, or `/kssettings` with KyuubiSoft Core) and the server language (`/kssettings`, or `language` in `config.json` without Core)

2. Verify language file exists in `localization/` folder

3. Check for JSON syntax errors in language file

4. Reload config with `/ksinfoadmin reload`

### Text Appears Cut Off

**Symptoms:**
- Buttons show "..." at end
- Text overlaps

**Solutions:**

1. Shorten translation text
2. Use abbreviations where appropriate
3. Split into multiple lines if supported

---

## Performance Issues

### Lag When Opening Info Hub

**Symptoms:**
- Delay before UI appears
- Server lag spike

**Solutions:**

1. Limit search results:
   ```json
   "globalSearch": {
     "maxResults": 10
   }
   ```

2. Disable unused sections

---

## JSON Validation

Many issues are caused by JSON syntax errors.

### Common JSON Errors

| Error | Fix |
|-------|-----|
| Missing comma | Add `,` between items |
| Extra comma | Remove trailing `,` |
| Missing quote | Ensure all strings have `"..."` |
| Missing bracket | Match all `{` with `}` and `[` with `]` |

### Validate JSON Online

Use [jsonlint.com](https://jsonlint.com) to check your files.

---

## Reload Configuration

After fixing config files:

```
/ksinfoadmin reload
```

It also works from the console and waits for a save of the admin window that is still running. New or renamed command names need a restart.

---

## Getting Help

If issues persist:

1. **Check server logs** for detailed errors
2. **Gather information:**
   - Server version
   - Plugin version
   - Config files
   - Error messages
3. **Report issue:**
   - Discord: [KyuubiSoft Discord](https://dc.gg/kyuubisoft)