evaluation-errors.rst

Evaluation errors

This document describes the different evaluation errors, depending on the evaluation modes. The obtained behaviors when these errors raise and the configuration options or command-line switches that change these behaviors.

Error kinds

The following list describes the different kind of evaluation error:

• bad code: modulefile has some code error (e.g., bad Tcl syntax, using undefined commands)
• break: use of break Tcl command in modulefile
• exit: use of exit Tcl command in modulefile
• error: use of error Tcl command in modulefile
• not found: designated modulefile cannot be found
• hard hidden: designated modulefile is hidden in --hard mode and cannot be found
• not loaded: when unloading a module, designated modulefile is not found loaded
• already loaded: when loading a module, designated modulefile is already loaded
• conflict: dependency issue where loading modulefile conflicts with at least one loaded module
• missing requirement: dependency issue where a loading modulefile has at least one requirement module not loaded
• dependent reload: dependency issue where a loading or unloading modulefile has at least one dependent module that fails to reload (either during the unload or load phase)
• unloading dependent: dependency issue where an unloading modulefile has at least one loaded module requiring it
• forbidden: evaluated modulefile is tagged forbidden
• sticky unload: when unloading a module tagged sticky
• super-sticky unload: when unloading a module tagged super-sticky

Note

Use of continue Tcl command in modulefile shortens evaluation but it is not considered an error.

Note

When a dependent reload issue occurs during the load or unload of a modulefile, the dependent module failing to reload has raised one of the following error kind: bad code, break, exit, error, conflict, missing requirement, forbidden or hard hidden.

Behavior when error raises

This section describes the behaviors generally obtained when the different error kinds raise.

Other specific behavior depending on evaluation mode or configuration options are described in the following parts of the document.

Default

Default behavior when an error raises:

• current modulefile evaluation is aborted
• an error message is reported
• exit code is set to 1

Ignored errors

The following error kinds are ignored errors:

• not loaded
• already loaded

These errors lead to a different behavior:

• current modulefile evaluation is skipped
• no message reported
• no error exit code set

Errors raised during modulefile evaluation

Following errors are raised during the Tcl evaluation of a modulefile:

• bad code
• break
• exit
• error
• conflict (also raised outside modulefile evaluation)
• missing requirement

Evaluation mode or options specific behaviors

Some error kinds only occur during specific evaluation mode or when configuration options are set to a given value.

Error kind	Evaluation mode	Configuration option
conflict	load
missing requirement	load
dependent reload	load, unload
unloading dependent	unload	when :mconfig:`auto_handling` is disabled
forbidden	load
hard hidden	load
already loaded	load
not loaded	unload
sticky unload	unload
super-sticky unload	unload

When evaluation mode and/or configuration option matches for these error kinds to raise, a :ref:`default error behavior<default>` error behavior is applied.

Load sub-command

Specific error behavior for modulefile load evaluation by :subcmd:`load` sub-command.

Force mode

When :option:`--force` command-line switch is used, load evaluation by-pass following errors:

• conflict
• missing requirement
• dependent reload

Following behavior is observed:

• evaluation continues (error is by-passed)
• warning message reported (instead of an error message)
• no error exit code set

Warning

Missing requirement and dependent reload errors currently returns an error exit code. This behavior might be aligned with the above one in the future. Or the above behavior may be adapted the other way around.

No effect on other error kinds as it is not useful to mark loaded a broken or nonexistent modulefile.

abort_on_error configuration option is ignored when --force option is in use. Which means continue on error behavior is applied.

Multiple modulefiles passed as argument

When multiple modulefiles are passed to the load sub-command for evaluation. If the evaluation of one modulefile raises an error, behavior for this error is applied and if:

• :mconfig:`abort_on_error` configuration option does not contain load or --force is set:
  • already evaluated modulefiles from the argument list are kept loaded
  • in case of an exit error, evaluation stops
  • for other kind of error, evaluation continues with next modulefile in argument list
• :mconfig:`abort_on_error` configuration option contains load and --force is not set:
  • already evaluated modulefiles from the argument list are withdrawn (they will not appear loaded and their environment changes are flushed)
  • evaluation stops

The above description only applies to load sub-command executed from the top level context and not from a modulefile evaluation. Multiple arguments on a module load command in modulefile are evaluated independently as an AND requirement list.

Warning

:command:`ml` command applies the abort_on_error behavior by default, whatever behavior is configured for load. Default behavior for load may be changed in next major version to align ml command behavior.

Load-any sub-command

Specific error behavior for modulefile load evaluation by :subcmd:`load-any` sub-command.

Following errors are ignored:

• not found
• forbidden
• hard hidden

However if no module is loaded after evaluating all load-any modulefile arguments:

• an error message is reported
• an error exit code is set

For other kind of error, relative error message is reported and error exit code is set. Even if a module is loaded after evaluating all modulefile arguments.

Force mode

Same force behavior observed than for Load sub-command.

Multiple modulefiles passed as argument

:subcmd:`load-any` stops evaluation process as soon as a modulefile argument is successfully loaded.

load-any is not a valid value element for :mconfig:`abort_on_error` configuration option.

exit error stops evaluation of remaining modulefiles in the argument list.

When module load-any is evaluated as a modulefile command:

• if one modulefile in the list is loaded
  • no error message is reported whatever the error kind
• if no modulefile in the list is loaded
  • an error message is reported for errors other than not found, forbidden and hard hidden
  • modulefile declaring the module load-any command raises a missing requirement error

Warning

An error message may also be reported for not found, forbidden and hard hidden error in the future when no modulefile in the list is loaded.

Warning

Error messages may be transformed into warnings and exit code may be untouched in the future if one modulefile in the list is loaded.

Try-load sub-command

Specific error behavior for modulefile load evaluation by :subcmd:`try-load` sub-command.

Following errors are ignored:

• not found
• forbidden
• hard hidden

Even if no module is loaded after evaluating all try-load modulefile arguments.

Force mode

Same force behavior observed than for Load sub-command.

Multiple modulefiles passed as argument

Same multiple modulefile arguments behavior is observed than for Load sub-command.

Except not found, forbidden and hard hidden errors are ignored even if :mconfig:`abort_on_error` configuration option contains try-load.

Mod-to-sh sub-command

Specific error behavior for modulefile load evaluation by :subcmd:`mod-to-sh` sub-command.

Same behavior is observed than for Load sub-command.

Reload sub-command

Specific error behavior for modulefile load evaluation by :subcmd:`reload` sub-command.

In case of any error (either during unload or load phase) evaluation stops and environment changes of already unloaded/loaded modules are flushed. Unless if force mode is enabled or if reload is removed from :mconfig:`abort_on_error` configuration option (where it is enabled by default). In this case, a continue on error behavior is applied.

Prior running evaluations, dependencies of loaded modules are checked. If at least one dependency (requirement or conflict) is not satisfied, an error is raised.

Purge sub-command

Specific error behavior for modulefile load evaluation by :subcmd:`purge` sub-command.

In case of error, continue on error behavior is applied. If purge is added in the value list of :mconfig:`abort_on_error` configuration option and if force mode is not set, abort on error behavior applies.

Unload sub-command

Specific error behavior for modulefile unload evaluation by :subcmd:`unload` sub-command.

Force mode

When :option:`--force` command-line switch is used, unload evaluation by-pass following errors:

• bad code
• break
• exit
• error
• dependent reload
• unloading dependent
• sticky unload

Following behavior is observed:

• evaluation continues (error is by-passed)
• warning message reported (instead of an error message)
• no error exit code set

When facing an erroneous modulefile, it seems useful to be able to get rid of it from user's loaded environment.

abort_on_error configuration option is ignored when --force option is in use. Which means continue on error behavior is applied.

Multiple modulefiles passed as argument

When multiple modulefiles are passed to the unload sub-command for evaluation. If the evaluation of one modulefile raises an error, behavior for this error is applied and if:

• :mconfig:`abort_on_error` configuration option does not contain unload or --force is set:
  • already evaluated modulefiles from the argument list are kept unloaded
  • for other kind of error, evaluation continues with next modulefile in argument list
• :mconfig:`abort_on_error` configuration option contains load and --force is not set:
  • already evaluated modulefiles from the argument list are withdrawn (they will appear loaded again and their environment changes are untouched)
  • evaluation stops

The above description only applies to unload sub-command executed from the top level context and not from a modulefile evaluation. Multiple arguments on a module unload command in modulefile are evaluated independently as an AND conflict list.

Warning

:command:`ml` command applies an abort behavior when facing an error. Evaluation stops and already unloaded modulefiles are restored in loaded environment. It may be changed in the next major version to align unload phase of ml command on unload sub-command behavior.

Note

exit error does not lead to an evaluation inhibit of remaining modulefiles when evaluation is made in unload mode. Unless if an exit error was previously raised in a load evaluation mode prior an unload phase.