Error Types

As mentioned before, adam uses multiple error types that behave differently when handled. Below is a list of all built-in errors.Error, the interface used to abstract errors generated by adam.

You may also encounter "normal" errors, that don't implement errors.Error, such as msgawait.TimeoutError. Those usually implement the interface used by errors.As to make themselves available as an errors.Error. Don't worry about this too much, the default error handler already takes care of the conversion for you.

errors.InformationalError

This error does nothing when handled and simply serves as a signaling error much like io.EOF.

There is also a default, errors.Abort, that can be used to signal a user-triggered stop of execution.

Constructors

• errors.NewInformationalError(desc string)

errors.InternalError

This is the most common error and is also created when using errors.WithStack. Everything that goes wrong during the execution and is not the user's fault, is considered an InternalError. By default they are logged.

InternalErrors can be divided into two categories:

Silent InternalErrors are errors that are logged via errors.Log, but their occurrence is not communicated to the user through a message. This is useful if a function can safely continue even though an error occurred, but the error shall still be captured.

Non-Silent InternalErrors are errors that are logged via errors.Log and send a message in the invoking channel. All constructors below that don't contain the word Silent produce such non-silent errors. By default a non-silent InternalError sends a generalized message, however, it can be customized using errors.WithDescription and it's derivatives.

You can also convert a silent error into a non-silent error and vice versa:

nonSilent      := errors.NewWithStack("something broke")
silent         := errors.Silent(nonSilentError)
nonSilentAgain := errors.WithStack(silent)

In the above example a new non-silent InternalError is created, converted into a silent InternalError, and converted back again.

Furthermore, all silent constructors discard non-InternalErrors, i.e. they return nil. This is done to prevent user-related errors, i.e. any error other than an InternalError, from sending messages as to not break the requested "silence". However, this rule does not apply to errors.MustSilent. Refer to it's doc for more information.

Constructors

• errors.NewWithStack(text string)

• errors.NewSilent(text string)

• errors.NewWithStackf(format string, a ...interface{})

• errors.NewSilentf(format string, a ...interface{})

• errors.WithStack(err error)

• errors.Silent(err error)

• errors.MustInternal(err error)

• errors.MustSilent(err error)

• errors.Wrap(err error, message string)

• errors.WrapSilent(err error, message string)

• errors.Wrapf(err error, format string, a ...interface{})

• errors.WrapSilentf(err error, format string, a ...interface{})

• errors.WithDescription(err error, description string)

• errors.WithDescriptionf(err error, format string, a interface{}...)

• errors.WithDescriptionl(err error, description *i18n.Config)

• errors.WithDescriptionlt(err error, description i18n.Term)

errors.UserError

A UserError is the type used to signal the user they did something wrong, and isn't logged.

It is basically an *embedutil.Builder, but uses a template embed to unify its style. You can customize the base embed using errors.SetErrorEmbed.

Defaults

• bot.ErrUnknownCommand

Constructors

• errors.NewCustomUserError()

• errors.NewUserErrorFromEmbed(e *embedutil.Builder)

• errors.NewUserError(description string)

• errors.NewUserErrorl(description *i18n.Config)

• errors.NewUserErrorlt(description i18n.Term)

errors.UserInfo

A UserInfo is less critical UserError. By default, its embed color is not red like its error counterpart but blue.

Constructors

• errors.NewCustomUserInfo()

• errors.NewUserInfoFromEmbed(e *embedutil.Builder)

• errors.NewUserInfo(description string)

• errors.NewUserInfol(description *i18n.Config)

• errors.NewUserInfolt(description i18n.Term)

plugin.ArgumentError

This error gets returned by plugin.ArgConfig if something is wrong with the arguments or flags supplied by the user. No logging here either.

Constructors

• plugin.NewArgumentError(description string)

• plugin.NewArguementErrorl(description *i18n.Config)

• plugin.NewArgumentErrorlt(description i18n.Term)

plugin.BotPermissionsError

This error gets returned every time the bot needs permissions to do something but hasn't. If that's the case, the user will be supplied a list of permissions they need to grant the bot in order to proceed.

Defaults

• plugin.DefaultBotPermissionsError

Constructors

• plugin.NewBotPermissionsError(missing discord.Permissions)

plugin.ChannelTypeError

A plugin.ChannelTypeError is used if a command is invoked in a channel with a channel type not allowed by the command. It lists the channel types allowed to use.

Constructors

• plugin.NewChannelTypeError(allowed plugin.ChannelType)

plugin.RestrictionError

If a plugin.RestrictionFunc fails, it typically returns this error. There are fatal and non-fatal plugin.RestrictionErrors, as marked by their .Fatal field. This is important for help commands to decide whether they should show the command in the help text: When listing all commands the help command checks each command whether it's restricted. If a command returns a fatal restriction, it is excluded from the list.

Defaults

• plugin.DefaultRestrictionError

• plugin.DefaultFatalRestrictionError

Constructors

• plugin.NewRestrictionError(description string)

• plugin.NewRestrictionErrorl(description *i18n.Config)

• plugin.NewRestrictionErrorlt(description i18n.Term)

• plugin.NewFatalRestrictionError(description string)

• plugin.NewFatalRestrictionErrorl(description *i18n.Config)

• plugin.NewFatalRestrictionErrorlt(description i18n.Term)

plugin.ThrottlingError

This error is returned by types implementing plugin.Throttler and indicates that the user is being throttled.

Constructors

• plugin.NewThrottlingError(description string)

• plugin.NewThrottlingErrorl(description *i18n.Config)

• plugin.NewThrottlingErrorlt(description i18n.Term)