Skip to main content

Common Issues

A list of problems we see most often, and how to fix them.

1. The AI is not responding​

Run /crafty status in-game. If it says "API key not configured", your key isn't set yet. If it says "Connection failed", your server can't reach our backend.

Things to check:

  • Your API key is in config.yml (plugin) or the mod settings
  • The key has no leading or trailing whitespace
  • Your server has outbound internet access on port 443
  • No firewall rule is blocking craftyai-gateway.workers.dev

2. "Invalid API key"​

The key in your config doesn't match what we have on file. Common causes:

  • You copied the key with extra whitespace
  • You rotated the key in-game but didn't update the config file
  • You're using a key from a different server

Fix: run /crafty apikey in-game to generate a fresh key, copy it, and paste it into your config.

3. "Connection timeout" / "Connection refused"​

Your server can't reach our backend. Check:

  • Outbound HTTPS (port 443) is allowed
  • No proxy is intercepting requests
  • The /crafty test command produces a more detailed error message

If you're behind a corporate firewall or proxy, you'll need to allowlist *.workers.dev.

4. The plugin or mod isn't loading​

  • Plugin: Make sure you're running Java 17 or higher. Java 8 works on old Minecraft versions but Java 17 is recommended.
  • Mod: Make sure you have the right JAR for your Minecraft version. On MC 1.26, use craftyai-fabric-26. On 1.20–1.21.1, use the standard craftyai-fabric.
  • Check the server console for a stack trace. The most common cause is a dependency missing from your mod loader.

5. Fabric mod crashes on startup​

You probably forgot to install Fabric API. Download it from Modrinth and put it in your mods/ folder alongside CraftyAI.

6. The Vision Scanner doesn't do anything​

  • Plugin: Make sure you're holding a Compass in your main hand, not just in your inventory.
  • Mod: Make sure you're pressing V, not B (which is the default for a different mod).
  • Check that enable_actions is true in your config.

7. The AI gives wrong answers about my server​

The AI doesn't know your server's custom rules unless you teach them. Use /crafty learn Q | A to teach it anything specific to your server (rules, locations, lore).

For example:

/crafty learn Where is spawn? | Spawn is at the giant oak tree in the plains biome.
/crafty learn What is the economy currency? | We use iron ingots as currency.

8. "Rate limited" errors​

You hit your tier's per-minute or per-day limit. The AI will start responding again when the window resets.

Check your tier in Discord with /my-sessions or in-game with /crafty pro status. If you need higher limits, see the Server Admin Guide for tier options.

9. Security strike warnings in console​

The plugin detected a request from a client that doesn't match the expected CraftyAI format. This is usually one of:

  • An outdated plugin or mod version on another server in your network
  • A non-Minecraft client (a script, a tool) using your server's session ID
  • A misconfigured proxy that rewrites the user agent

Check the source IP in the warning. If it's one of your servers, update the plugin or mod. If it's external, rotate your API key with /crafty apikey.

10. Config changes don't take effect​

Run /crafty reload after editing config.yml. The plugin reads the config on startup and on reload, not on every request.

If /crafty reload doesn't pick up your changes, check file permissions. On Linux, the user running the server needs read access to config.yml.

11. AI responses are slow​

A few possible causes:

  • Your tier's rate limit is low and requests are being queued
  • The AI provider is having an outage (check status.craftyai.com for live status)
  • Your network has high latency to our backend

If slow responses are constant, check /crafty status for your average response time.

Make sure you're using the right command order:

  1. In Minecraft: /crafty link (generates a 6-character code)
  2. In Discord: /link <code> (redeems the code)

Codes expire after 15 minutes. If you generated the code more than 15 minutes ago, run /crafty link again to get a new one.