Skip to main content

Exception Reference

This page provides detailed information about all exception types that can be thrown by M-Files UI Extension methods.

Error Hierarchy​

Exception Hierarchy:

  • Error (JavaScript base class)
    • MFilesError (M-Files base class)
      • All M-Files specific exceptions (ArgumentError, NotFoundError, etc.)

All M-Files specific exceptions inherit from MFilesError, which itself inherits from the standard JavaScript Error class. This means you can catch M-Files errors using MFilesError for any M-Files-related error, or catch specific derived types for more granular error handling.

Standard JavaScript Exceptions​

In addition to M-Files specific exceptions, UI Extension methods may also throw standard JavaScript exceptions such as Error, TypeError, RangeError, ReferenceError, SyntaxError, and URIError. For comprehensive documentation on JavaScript exceptions, refer to the MDN JavaScript Error Reference.

Error Handling Examples​

For examples of handling different error types in your code, see the Error Handling Sample.

M-Files Exception Types​

ArgumentError​

Thrown when one of the arguments provided to a method is not valid.

Common Causes:

  • Invalid parameter values (null, undefined, negative numbers where not allowed)
  • Arguments out of valid range
  • Incorrect argument types or formats
  • Missing required parameters

Examples:

// Invalid command ID
if (commandId < 0) {
  throw new ArgumentError("Command ID must be non-negative");
}

ConfigurationError​

Thrown when a configuration value is invalid or missing.

Common Causes:

  • Missing required configuration values
  • Invalid configuration format or syntax
  • Configuration file not found or not readable
  • Incompatible configuration for current environment

Examples:

// Missing required configuration
if (!config.apiKey) {
  throw new ConfigurationError("API key is required");
}

DuplicateCommandError​

Thrown when an operation on a command fails due to the command already existing in the target location.

Common Causes:

  • Adding the same command to a menu location multiple times
  • Command ID collision
  • Attempting to create a command that already exists

Examples:

// Attempting to add duplicate command to menu
if (menuAlreadyContainsCommand(commandId)) {
  throw new DuplicateCommandError("Command already exists in this menu");
}

InvalidOperationError​

Thrown when a method call is not valid for the object's current state.

Common Causes:

  • Object not properly initialized
  • Operation called in wrong state or lifecycle phase
  • Resource locked or unavailable
  • Method called on disposed object

Examples:

// Operation called before initialization
if (!this.isInitialized) {
  throw new InvalidOperationError("Object must be initialized first");
}

MFilesError​

Base class for all M-Files UI Extension exceptions.

NotFoundError​

Thrown when an object, command, or resource cannot be found.

Common Causes:

  • Command or menu item deleted or does not exist
  • Invalid command or object reference
  • Resource removed from vault
  • Attempting to access another application's commands

Examples:

// Command not found in vault
const command = this.findCommand(commandId);
if (!command) {
  throw new NotFoundError(`Command ${commandId} not found`);
}

NotSupportedError​

Thrown when an operation is not supported in the current context.

Common Causes:

  • Feature not available in current M-Files version
  • Operation not supported for specific object type
  • Platform limitations (e.g., web vs desktop)
  • Feature behind a feature flag that is disabled

Examples:

// Feature not available
if (!this.supportsFeature(feature)) {
  throw new NotSupportedError("Feature not available in this version");
}

TimeoutError​

Thrown when an operation times out.

Common Causes:

  • Network latency or connectivity issues
  • M-Files server not responding
  • Long-running vault operations
  • Client-side operation taking too long

Examples:

// Operation timeout
if (elapsed > timeout) {
  throw new TimeoutError("Operation timed out after 30 seconds");
}

UnauthorizedAccessError​

Thrown when access to a resource is denied due to insufficient permissions.

Common Causes:

  • User lacks required vault permissions
  • Object is checked out by another user
  • Vault access restrictions
  • Application does not own the resource (e.g., trying to modify another app's commands or taskbar groups)

Examples:

// User lacks permissions
if (!user.hasPermission(Permission.Write)) {
  throw new UnauthorizedAccessError("Write permission required");
}

JavaScript Exception Types​

These are standard JavaScript exceptions that may be thrown by UI Extension methods. For complete documentation, see the MDN JavaScript Error Reference.

Error​

The Error object represents an error when trying to execute a statement or accessing a property.

Common Causes:

  • Generic error condition
  • Uncaught exceptions
  • Manual error throwing

RangeError​

The RangeError object indicates an error when a value is not in the set or range of allowed values.

Common Causes:

  • Array length out of bounds
  • Invalid numeric values
  • Recursive function limits

ReferenceError​

The ReferenceError object represents an error when trying to access a variable that is not defined.

Common Causes:

  • Accessing undefined variables
  • Typos in variable names
  • Scope issues

SyntaxError​

The SyntaxError object represents an error when trying to interpret syntactically invalid code.

Common Causes:

  • Malformed JSON
  • Invalid regular expressions
  • Parse errors

TypeError​

The TypeError object represents an error when an operation could not be performed, typically when a value is not of the expected type.

Common Causes:

  • Calling a non-function
  • Accessing properties of null/undefined
  • Wrong argument types

URIError​

The URIError object represents an error when a global URI handling function was used in a wrong way.

Common Causes:

  • Invalid URI encoding/decoding
  • Malformed URI components