Errors

Most mistakes in a script stop it until its next start. Knowing which ones do, where they show up and how their texts are built saves a lot of guessing.

Where errors show up

When the code couldn't be loaded, the bot's Settings tab gives the reason under Package settings, as The entry function explains.

The alert goes away when the script starts again, when you load or unload a package, or when the bot disconnects. Dismiss only hides the text you dismissed: a different error shows up again.

What stops a script

The text in the alert starts with where the failure happened:

A few failures have their own text, whichever of the beginnings above comes first:

The default export has its own three errors, listed in The entry function.

Reading an error text

After the beginning comes the error itself.

An error your code threw shows as its type and message, such as Error: no zaap on this map or TypeError: gamedata.record id must be an integer. When it was thrown by a handler or a selector function that isn't async, at follows, with the file, the line and the column where it happened.

An error from an Asterobot function shows Asterobot's text. Promise rejected: in front of it means an await rejected. For example, sending token instead of ticketKey while the script starts gives:

initialize behavior module "library/my-first-script/1.0.0/index.js": Promise rejected: IdentificationRequest.token: unknown protobuf field

Error messages lists the texts of Asterobot's functions, with their causes.

What doesn't stop a script

The logging functions, botInfo() and the others, never throw.

Functions that throw right away

A few functions throw as soon as they're called, instead of returning a promise that rejects. A try/catch catches them without any await:

Keep a script running

A handful of habits prevent most failures, and every sample in these docs follows them:

• Put each await of a handler inside try/catch. An error that escapes a handler, async or not, stops the whole script.
• Check that traffic.payload exists before reading its fields: a message Asterobot couldn't decode has no payload. traffic.payload?.content checks and reads at once.
• Give every wait() a timeout. Without one, a wait that never matches stays open until the script stops. Open the wait before you send what it answers, as Waiting shows.
• When you start an async function without awaiting it, catch its errors, inside it or where you start it: refreshLoop().catch((error) => botWarn("Loop stopped:", String(error)));.
• Check what lookups return. undefined means nothing was found, or that the bot's game version has no game data.
• Convert BigInt ids with Number() before you pass them to record() or text().
• Log errors as String(error). Logging and debugging explains why.
• On a Full socket bot, make sure nothing after the identification can fail while the script starts. Otherwise the next start is "initial" again, and the script identifies a second time.

This handler reads chat lines starting with !json and parses what follows. Without the try, anyone typing !json { in a channel your character reads would stop the script:

import { session, botInfo, botWarn } from "asterobot:bot";
import { on, send } from "asterobot:protocol";

export default async function behavior(launch) {
  on("ChatChannelMessageEvent", (traffic) => {
    const content = traffic.payload?.content;
    if (!content?.startsWith("!json ")) return;

    try {
      const data = JSON.parse(content.slice(6));
      botInfo("Parsed:", JSON.stringify(data));
    } catch (error) {
      // An error that escapes a handler stops the whole script.
      botWarn("Not valid JSON:", String(error));
    }
  });

  // A new game connection starts with this message. MITM bots never launch
  // with "initial": the Dofus client has already identified their session.
  if (launch.reason === "initial") {
    await send("IdentificationRequest", {
      ticketKey: session.gameToken,
      languageCode: session.language,
    });
  }
}

Limits lists every limit and what happens past it. Next, Logging and debugging.