Debugging modules

A command does nothing, a hook never fires, or a cron job skips a run. Here is how to find out why.

1. Check the module’s health

1. Open your server, then Modules → Installed.
2. Click the module.

The top of the installation page shows Runs / 24h, Failures / 24h and Success Rate / 24h, plus a Components count of its commands, hooks and cron jobs.

• Failures above 0? Open the installation’s Events tab and turn on Failed only, or follow step 2.
• Runs at 0? The code never ran. Skip to Common causes.

2. Find the failed runs in Events

Every time a command, hook, cron job or shop action finishes, Takaro records an event:

Event	What ran
command-executed	A chat command
hook-executed	A hook
cronjob-executed	A cron job
shop-action-executed	A shop action

To see only the failures:

1. Open Events (for all servers) or your server → Events.
2. Turn on Failed only.
3. Use Add filter → Module to narrow it down to one module. You can also filter by Player, Game server or Event type.

Or type what you want in Filter with Takaro AI, for example “failed hooks from teleports last night”. Takaro AI turns it into filters.

Each failed row shows a ✗ and the error message. See Events for more on filters and time ranges.

3. Read the details

Click a failed event to open its details:

• Related: the player, server and module involved.
• Code: a link straight to the command, hook or cron job in the module.
• Raw JSON: the full record. Look at meta.result:
  • success: false for a failed run.
  • reason: the error message.
  • logs: every line the module wrote while it ran. Module authors write these with console.log.

Ask Takaro AI why it failed

Failed runs show a Takaro AI box in the details. Click Why did this fail? and Takaro AI reads the run and explains it in plain words.

After the explanation you can click Fix it with Takaro AI. For a module that isn’t your own (for example a built-in one) the button says Copy and fix it with Takaro AI: Takaro AI makes an editable copy first and leaves the original alone.

Note

The fix changes the module’s draft. Your server keeps running its installed version, and keeps failing, until you install the fixed version there.

Takaro AI can’t change shop actions. Fix those in the module editor.

Common causes

Some problems stop a run before it starts. These don’t create a command-executed event, so check them when you see no runs at all.

Cause	What happens	Fix
Missing permission	The player gets a chat message naming the permission. A command-execution-denied event is recorded.	Grant the permission to one of the player’s roles. See Roles and permissions.
Module disabled	Nothing runs.	Configure the module and turn enabled back on in System Config.
Command, hook or cron job disabled	That one part doesn’t run.	Configure the module and turn it back on in System Config.
Cooldown	The player gets a chat message saying when they can use the command again.	Lower the cooldown in System Config.
Not enough currency	The player gets “You do not have enough currency to execute this command.”	Lower the command’s cost, or give the player currency. See Economy.
Wrong command prefix	The chat message isn’t seen as a command.	Check Command Prefix in Settings. The default is /.
Wrong config	The code runs but does the wrong thing, or fails.	Click Configure and check the User Config. Explain these settings helps.
Version without the feature	The installed version doesn’t have that command or hook.	Install a newer version. See Versions and updates.

Some failures are on Takaro’s side, not in the module, for example when a run is rate limited. Takaro AI won’t offer a module fix for those.

Tip

To tell players when they type a command that doesn’t exist, turn on Unknown Command Feedback Enabled in Settings.

Test without waiting for a player

• Cron jobs: on the installation page, click Run now. The result shows up in Events.
• Any part of your own module: open it in the module editor and click Run test. You pick the server, and a player for commands. The result shows the status, the reason and the log lines. A skipped run tells you why, for example a cooldown or a disabled module.

Run test needs the Manage Modules permission. Testing a command also needs Read Players.