Handling Errors

With Seyfert, you can handle errors in an organized way and treat them differently depending on the type of error.

Error when executing a command

This is the most common error and occurs when an error is thrown in the run method.

import { , type  } from "seyfert";

export class  extends  {
  async (: ) {
    throw new ("Error, ehm, lol player detected");
  }

// : This responds with the previous error message: "Error, ehm, lol player detected"
  async (: , : unknown) {
    ...();
    await .({
      :  instanceof  ? . : `Error: ${}`
    });
  }
}

Error when validating options

This error is thrown when an option fails in the value method.

const  = {
  : ({
    : 'how to be a gamer',
    (, : <URL>, ) {
        if ((.)) return (new (.));

// This will trigger the onOptionsError method
        ('expected a valid URL');
    },
  })
};

@()
export class  extends  {
    async (
        : ,
        : 
    ) {
// : url: expected a valid URL
    await .({
      : .()
        .(() => [1].)
        .(() => `${[0]}: ${[1].}`)
        .("\n")
    });
  }
}

Stop a middleware with an error

When a middleware returns a stop, Seyfert generates this error and stops the progress of the command being handled.

import {  } from "seyfert";

export default <void>(({ , , ,  }) => {
    if (!.(..)) {
        return ("User is not a developer");
    }
    ();
});

import { , , type  } from "seyfert";

@(["OnlyDev"])
export class  extends  {
    async (: , : string) {
        await .({
// : User is not a developer
            : 
        });
    }
}

Missing member permissions

When a member doesn't have the required permissions specified in defaultMemberPermissions:

import { , type , type  } from "seyfert";

export class  extends  {
  async (: , : ) {
    await .({
      : `You need the following permissions: ${.(', ')}`,
    });
  }
}

Missing bot permissions

When the bot doesn't have the permissions specified in botPermissions:

import { , type , type  } from "seyfert";

export class  extends  {
  async (: , : ) {
    await .({
      : `I need the following permissions: ${.(', ')}`,
    });
  }
}

Lifecycle Hooks

Beyond error handlers, Seyfert provides lifecycle hooks for additional control:

import { , type , type UsingClient } from "seyfert";

export class  extends  {
  // Called before middlewares run
  async (: ) {}

  // Called before options are parsed — useful for early deferral
  async (: ) {
    await .();
  }

  // Called after run() completes (with error if thrown)
  async (: , ?: unknown) {}

  // Called on internal Seyfert errors
  async (: UsingClient, : unknown) {}
}

Default Error Handlers

Instead of defining error handlers on every command, you can set defaults in the Client constructor:

import { Client } from "seyfert";

const client = new Client({
  commands: {
    defaults: {
      onRunError: (context, error) => {
        context.editOrReply({ content: 'Something went wrong!' });
      },
      onOptionsError: (context) => {
        context.editOrReply({ content: 'Invalid options provided.' });
      },
      onPermissionsFail: (context, permissions) => {
        context.editOrReply({ content: `Missing permissions: ${permissions.join(', ')}` });
      },
      onBotPermissionsFail: (context, permissions) => {
        context.editOrReply({ content: `I need: ${permissions.join(', ')}` });
      },
      onMiddlewaresError: (context, error) => {
        context.editOrReply({ content: error });
      },
      onInternalError: (client, error) => {
        client.logger.fatal(error);
      },
    },
  },
  // Defaults for component handlers
  components: {
    defaults: {
      onRunError: (context, error) => {
        context.editOrReply({ content: 'Component error!' });
      },
    },
  },
  // Defaults for modal handlers
  modals: {
    defaults: {
      onRunError: (context, error) => {
        context.editOrReply({ content: 'Modal error!' });
      },
    },
  },
});

Per-command error handlers override the defaults. If a command defines its own onRunError, the default won't be called for that command.