Exceptions

Kord Extensions provides a number of extra exception types. These are useful for understanding precisely what went wrong in specific situations, but there are some exceptions that provide extra functionality when writing your extensions.

The global base type for extensions provided by Kord Extensions is KordExException. This type provides no extra functions or properties, and it directly extends Exception.

Functional Exceptions

The following exceptions don't necessarily represent programming errors. Instead, they exist to implement a framework feature, and you can use them freely for their intended purposes.

Discord Relayed

This exception is used when your extension code needs to bail for some reason, whilst providing a message that should be relayed to the actioning user if there is one.

The type for this exception is DiscordRelayedException.

This exception supports the following extra properties:

Name	Type	Description
`reason`	`Key?`	Translation Key object used to generate the `reason` string.

General Exceptions

Argument Parsing

This exception is thrown when something goes wrong during command argument parsing.

The type for this exception is ArgumentParsingException. Additionally, this exception extends DiscordRelayedException, rather than the base KordExException type.

This exception supports the following extra properties:

Name	Type	Description
`argument`	`Argument <*>?`	The `Argument` object representing the argument that failed to parse.
`arguments`	`Arguments`	The `Arguments` object containing the full set of arguments defined for this command.
`parser`	`StringParser?`	The tokenizing string parser which was used to parse the given `argument`. Will be `null` if this isn't a chat command.

Command Registration

This exception is thrown when an attempt to register a chat command fails. This may happen when:

A command with the given name was registered previously.
A command with the given alias was registered previously.
The command was previously registered under another name. An alias should be used instead of trying to do this.

The type for this exception is CommandRegistrationException.

This exception supports the following extra properties:

Name	Type	Description
`name`	`Key`	Key object representing the name of the command that failed to be registered.
`reason`	`Key`	Key object representing the human-readable string explaining why the command couldn't be registered.

There is no equivalent exception thrown for other command types.

Event Handler Registration

This exception is thrown when an attempt to register an event handler fails. This may happen when:

The event handler was already registered previously.

The type for this exception is EventHandlerRegistrationException.

This exception supports the following extra properties:

Name	Type	Description
`reason`	`String`	The human-readable string explaining why the event handler couldn't be registered.

Invalid Argument

This exception is thrown when a converter builder hasn't been set up properly, thus resulting in an invalid command argument. This usually happens when a required property is missing from the converter builder, or a property has otherwise been configured incorrectly.

The type for this exception is InvalidArgumentException.

This exception supports the following extra properties:

Name	Type	Description
`builder`	`ConverterBuilder <*>`	The converter builder that failed to validate. For more information, see the dedicated documentation.
`reason`	`String`	The human-readable string explaining why this argument failed to validate.

Invalid Command

This exception is thrown when a command fails to validate, thus resulting in an invalid command. This happens when a command's registration requirements aren't met. For more information, see the relevant section in the commands framework documentation.

The type for this exception is InvalidCommandException.

This exception supports the following extra properties:

Name	Type	Description
`name`	`Key?`	Key object representing the name of the command that failed to validate. This will be `null` if the command failed to validate because it wasn't given a name.
`reason`	`String`	The human-readable string explaining why this command failed to validate.

Invalid Event Handler

This exception is thrown when an event handler fails to validate, thus resulting in an invalid event handler. This may happen when:

The event handler does not have a defined action.

The type for this exception is InvalidEventHandlerException.

This exception supports the following extra properties:

Name	Type	Description
`reason`	`String`	The human-readable string explaining why this event handler failed to validate.

Invalid Extension

This exception is thrown when an extension fails to validate, thus resulting in an invalid extension.

Exception Info

The type for this exception is InvalidExtensionException.

This exception supports the following extra properties:

Name	Type	Description
`clazz`	`KClass <out Extension>`	The invalid extension's class.
`reason`	`String?`	The human-readable string explaining why this extension failed to validate.

Parser Exceptions

Kord Extensions contains a number of useful Parsers ⏳ that are mostly used by Converters. When a parser fails to parse a value, it will throw an extension that extends the BaseParserException type.

This type provides no extra functions or properties, and it directly extends KordExException.

Duration Parser

This is a generic exception, extended by more concrete types. It's also thrown directly by duration parsers when:

The parser is provided with a string containing a different number of units and values. Duration parsers require an equal number of units and values, as bare numbers are not supported.

The type for this exception is DurationParserException.

This exception supports the following extra properties:

Name	Type	Description
`error`	`Key`	Key object representing the human-readable string explaining what went wrong.

Invalid Time Unit

This exception is thrown when a duration parser encounters an invalid or unsupported time unit when parsing.

The type for this exception is InvalidTimeUnitException. Additionally, this exception extends DurationParserException, rather than the base KordExException type.

This exception supports the following extra properties:

Name	Type	Description
`unit`	`String`	The invalid or unsupported time unit encountered.

Last modified: 20 November 2024