Troubleshooting

Common issues and their solutions

"API KEY NOT CONFIGURED" Warning

You see this warning in the console if your API key isn't set. 

========================================================
  API KEY NOT CONFIGURED!
  Your Hycompanion API key is not set in config.yml
  
  Get your API key from: https://app.hycompanion.dev
  Then use: /hycompanion register <your-api-key>
========================================================
Solution

Use the command /hycompanion register <your-api-key> or edit config.yml manually.

NPCs Not Appearing with Custom Roles

Custom NPC roles (appearance, health, etc.) require a server restart after the initial sync because Hytale loads assets before the plugin can connect to the backend.

Solution
  1. Create NPCs in the dashboard
  2. Start the server → NPCs sync → Roles are cached
  3. Restart the server → Cached roles are loaded
  4. NPCs now have custom appearances

Connection Failed

The plugin can't connect to the backend.

Solution
  1. Check your API key is correct
  2. Verify your server can reach api.hycompanion.dev
  3. Check firewall settings
  4. Run /hycompanion status to see connection details

NPCs Not Responding

The NPC is visible but doesn't reply when players talk to them.

Solution
  1. Check the player is within chat_range (default: 15 blocks)
  2. Verify NPCs are synced: /hyc list
  3. Sync them using: /hyc sync
  4. Make the plugin scan them: /hyc scan
  5. Check connection: /hycompanion status
  6. Make sure you OpenRouter API key is configured for the server
  7. Choose another model in the dashboard
  8. Enable debug mode in config for more info

Plugin won't load

The server starts but Hycompanion doesn't appear in the plugin list.

Solution
  1. Make sure you're using a compatible Hytale server version
  2. Check that the JAR file is named correctly (no spaces)
  3. Look for errors in the server console at startup
  4. Verify the JAR file isn't corrupted - redownload from the dashboard
  5. Ensure the mods/ folder has proper write permissions

Rate limit exceeded

NPCs stop responding and logs show "rate limit" errors.

Solution
  1. Wait a few minutes - rate limits reset automatically
  2. Check your OpenRouter tier and usage limits
  3. Consider switching to a model with higher rate limits
  4. Add rate limiting in your NPC config to slow down requests
  5. Upgrade your OpenRouter tier if needed

Still stuck?

Join our Discord community for personalized help from the team and other users.

Join Discord