ReFrame Errors

When writing ReFrame tests, you don’t need to check for any exceptions raised. The runtime will take care of finalizing your test and continuing execution.

Dealing with ReFrame errors is only useful if you are extending ReFrame’s functionality, either by modifying its core or by creating new regression test base classes for fulfilling your specific needs.


This API is considered a developer’s API, so it can change from version to version without a deprecation warning.

exception reframe.core.exceptions.AbortTaskError(*args)[source]

Bases: ReframeError

Raised by the runtime inside a regression task to denote that it has been aborted due to an external reason (e.g., keyboard interrupt, fatal error in other places etc.)

exception reframe.core.exceptions.BuildError(stdout, stderr, prefix=None)[source]

Bases: ReframeError

Raised when a build fails.

exception reframe.core.exceptions.BuildSystemError(*args)[source]

Bases: ReframeError

Raised when a build system is not configured properly.

exception reframe.core.exceptions.CommandLineError(*args)[source]

Bases: ReframeError

Raised when an error in command-line arguments occurs.

exception reframe.core.exceptions.ConfigError(*args)[source]

Bases: ReframeError

Raised when a configuration error occurs.

exception reframe.core.exceptions.ContainerError(*args)[source]

Bases: ReframeError

Raised when a container platform is not configured properly.

exception reframe.core.exceptions.DependencyError(*args)[source]

Bases: ReframeError

Raised when a dependency problem is encountered.

exception reframe.core.exceptions.EnvironError(*args)[source]

Bases: ReframeError

Raised when an error related to an environment occurs.

exception reframe.core.exceptions.FailureLimitError(*args)[source]

Bases: ReframeError

Raised when the limit of test failures has been reached.

exception reframe.core.exceptions.ForceExitError(*args)[source]

Bases: ReframeError

Raised when ReFrame execution must be forcefully ended, e.g., after a SIGTERM was received.

exception reframe.core.exceptions.JobBlockedError(msg=None, jobid=None)[source]

Bases: JobError

Raised by job schedulers when a job is blocked indefinitely.

exception reframe.core.exceptions.JobError(msg=None, jobid=None)[source]

Bases: ReframeError

Raised for job related errors.

property jobid

The job ID of the job that encountered the error.

exception reframe.core.exceptions.JobNotStartedError(msg=None, jobid=None)[source]

Bases: JobError

Raised when trying an operation on a unstarted job.

exception reframe.core.exceptions.JobSchedulerError(*args)[source]

Bases: ReframeError

Raised when a job scheduler encounters an error condition.

exception reframe.core.exceptions.LoggingError(*args)[source]

Bases: ReframeError

Raised when an error related to logging has occurred.

exception reframe.core.exceptions.NameConflictError(*args)[source]

Bases: RegressionTestLoadError

Raised when there is a name clash in the test suite.

exception reframe.core.exceptions.PerformanceError(*args)[source]

Bases: ReframeError

Raised to denote an error in performance checking, e.g., when a performance reference is not met.

exception reframe.core.exceptions.PipelineError(*args)[source]

Bases: ReframeError

Raised when a condition prevents the regression test pipeline to continue and the error may not be described by another more specific exception.

exception reframe.core.exceptions.ReframeBaseError(*args)[source]

Bases: BaseException

Base exception for any ReFrame error.

This exception base class offers a specialized __str__() method that concatenates the messages of a chain of exceptions by inspecting their __cause__ field. For example, the following piece of code will print error message 2: error message 1:

 from reframe.core.exceptions import *

 def foo():
     raise ReframeError('error message 1)

 def bar():
     except ReframeError as e:
         raise ReframeError('error message 2') from e

if __name__ == '__main__':
    except Exception as e:
exception reframe.core.exceptions.ReframeError(*args)[source]

Bases: ReframeBaseError, Exception

Base exception for soft errors.

Soft errors may be treated by simply printing the exception’s message and trying to continue execution if possible.

exception reframe.core.exceptions.ReframeFatalError(*args)[source]

Bases: ReframeBaseError

A fatal framework error.

Execution must be aborted.

exception reframe.core.exceptions.ReframeSyntaxError(*args)[source]

Bases: ReframeError

Raised when the syntax of regression tests is incorrect.

exception reframe.core.exceptions.RegressionTestLoadError(*args)[source]

Bases: ReframeError

Raised when the regression test cannot be loaded.

exception reframe.core.exceptions.RunSessionTimeout(*args)[source]

Bases: ReframeError

Raised when the maximum duration for a test session expires.

exception reframe.core.exceptions.SanityError(*args)[source]

Bases: ReframeError

Raised to denote an error in sanity checking.

exception reframe.core.exceptions.SkipTestError(*args)[source]

Bases: ReframeError

Raised when a test needs to be skipped.

exception reframe.core.exceptions.SpawnedProcessError(args, stdout, stderr, exitcode)[source]

Bases: ReframeError

Raised when a spawned OS command has failed.

property command

The command that the spawned process tried to execute.

property exitcode

The exit code of the process.

property stderr

The standard error of the process as a string.

property stdout

The standard output of the process as a string.

exception reframe.core.exceptions.SpawnedProcessTimeout(args, stdout, stderr, timeout)[source]

Bases: SpawnedProcessError

Raised when a spawned OS command has timed out.

property timeout

The timeout of the process.

exception reframe.core.exceptions.StatisticsError(*args)[source]

Bases: ReframeError

Raised to denote an error in dealing with statistics.

exception reframe.core.exceptions.TaskDependencyError(*args)[source]

Bases: ReframeError

Raised inside a regression task by the runtime when one of its dependencies has failed.

exception reframe.core.exceptions.TaskExit(*args)[source]

Bases: ReframeError

Raised when a regression task must exit the pipeline prematurely.

reframe.core.exceptions.is_exit_request(exc_type, exc_value, tb)[source]

Check if the error is a request to exit.

reframe.core.exceptions.is_severe(exc_type, exc_value, tb)[source]

Check if exception is a severe one.

reframe.core.exceptions.is_user_error(exc_type, exc_value, tb)[source]

Check if error is a user programming error.

A user error is any of AttributeError, NameError, ModuleNotFoundError, TypeError or ValueError and the exception isthrown from user context.

reframe.core.exceptions.is_warning(exc_type, exc_value, tb)[source]

Check whether this exception can be treated as warning

reframe.core.exceptions.user_frame(exc_type, exc_value, tb)[source]

Return a user frame from the exception’s traceback.

As user frame is considered the first frame that is outside from reframe module.


A frame object or None if no user frame was found.

reframe.core.exceptions.what(exc_type, exc_value, tb)[source]

A short description of the error.