﻿---
title: Errors
description: Errors and status codes, the library version, and the cancel flag that stops a long call.
url: https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/
---

# Errors – Python API Reference – Deformable v0.1.0

What a failed call reports: the [`Status`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status) that names what went wrong, and the [`DeformableError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#deformableerror) that carries it. Then the library version, and the [`CancelFlag`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#cancelflag) that stops a long call from another thread.

## DeformableError

**Exception** · `deformable.DeformableError`

```python
class DeformableError(Exception):
    def __init__(
        self,
        status: Status | int,
        message: str,
        first_index: int = 0,
        second_index: int = 0,
    )
```

A library call failed: its status, the library's message and up to two element indices.

The indices name the tetrahedron, region, polygon, face, vertex or edge the failure concerns, or the trial's tetrahedron count and limit, as each [`Status`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status) member says; they are 0 when the status names none. `str(error)` is the status name, a colon and the message. Arguments the package refuses before calling the library raise ValueError or TypeError instead.

**Fields**

- `status` ([`Status`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status) or `int`): What went wrong; a plain int for a code a newer library returns that this package does not know yet.
- `message` (`str`): The library's message, in English. A [`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror)'s is written for the user, to show as it is.
- `first_index` (`int`): The first element index the status names (the tetrahedron, region, polygon, face, vertex or edge's first vertex, or the tetrahedrons that would take part in a trial scene), or 0. Default `0`.
- `second_index` (`int`): The second element index the status names (the region's polygon, the edge's second vertex, or the trial's tetrahedron limit), or 0. Default `0`.

**Example**

```python
try:
    scene.set_worker_count(0)
except deformable.DeformableError as error:
    print(error.status.name, error.first_index)
# INVALID_WORKER_COUNT 0
```

**See also** [Guide: DeformableError](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#deformableerror) · [C `DeformableErrorDetails`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformableerrordetails) · [Rust `Error`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#error)

## Status

**Enum** · `deformable.Status`

```python
class Status(enum.IntEnum):
    OK = 0
    NULL_POINTER = 1
    INVALID_ARGUMENT = 2
    PANICKED = 3
    INDEX_OUT_OF_RANGE = 4
    UNKNOWN_MATERIAL = 5
    UNKNOWN_OBJECT = 6
    LENGTH_MISMATCH = 7
    NON_FINITE_VALUE = 8
    EMPTY_MESH = 9
    NON_MANIFOLD_FACE = 10
    DEGENERATE_TETRAHEDRON_TOO_SMALL = 11
    DEGENERATE_TETRAHEDRON_FLAT = 12
    DEGENERATE_TETRAHEDRON_INVERTED = 13
    SCALE_OUT_OF_RANGE = 14
    DEGENERATE_REGION = 15
    TIME_WENT_BACKWARDS = 16
    INVALID_WORKER_COUNT = 17
    CANCELLED = 18
    OUTPUT_TOO_LARGE = 19
    DEGENERATE_POLYGON = 20
    NON_MANIFOLD_EDGE = 21
    NON_CLOSED_BOUNDARY = 22
    COULD_NOT_CONVERGE = 23
    BAD_SCALES = 24
    MESHING_FAILED = 25
    NO_TETRAHEDRONS = 26
    INVALID_CAGE = 27
    NON_POSITIVE_THICKNESS = 28
    NOT_ISOMORPHIC = 29
    UNKNOWN_VERTEX = 30
    DUPLICATE_VERTEX = 31
    MULTIPLE_BOUNDARIES = 32
    DEGENERATE_FACE = 33
    NULL_NORMAL = 34
    EMPTY_INPUT = 35
    STEP_LIMIT_REACHED = 36
    INVALID_SPLINTER_CAGE = 37
    EMPTY_IMAGE = 38
    NO_VERTICES = 39
    NO_CELLS = 40
    ENDLESS_CYCLE = 41
    FACE_ALREADY_SET = 42
    SINGULAR_TRANSFORM = 43
    LICENSE_REQUIRED = 44
    TRIAL_LIMIT_EXCEEDED = 45
    LICENSE_NEEDS_ONLINE = 46
    LICENSE_SERVICE_UNAVAILABLE = 47
    LICENSE_KEY_REJECTED = 48
    LICENSE_STORAGE_FAILED = 49
```

What a failed library call reports, in [`DeformableError.status`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#deformableerror): one member per status code of the library.

The indices of the [`DeformableError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#deformableerror) name the element a status concerns, as each member says; they are 0 when it names none. A newer library can add statuses: a code this package does not know comes as a plain int.

**Values**

- `OK` (`0`): The call succeeded; no [`DeformableError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#deformableerror) carries it.
- `NULL_POINTER` (`1`): A required argument was missing at the library boundary. The package never lets one through, so seeing it means a defect in this package.
- `INVALID_ARGUMENT` (`2`): An argument the library cannot read: an enumeration value it does not define, an array larger than the address space, or a material preset name it does not ship. The license calls give it for text that is no license key, and for another key while one is stored.
- `PANICKED` (`3`): The library panicked; the objects the call used should be closed.
- `INDEX_OUT_OF_RANGE` (`4`): An index points past the end of the list it indexes; for the polygon tools `first_index` names the polygon.
- `UNKNOWN_MATERIAL` (`5`): A material handle names no material of the scene.
- `UNKNOWN_OBJECT` (`6`): An object handle names no object of the scene, or a removed one.
- `LENGTH_MISMATCH` (`7`): A list does not have the length its partner requires.
- `NON_FINITE_VALUE` (`8`): A position or parameter is NaN or infinite.
- `EMPTY_MESH` (`9`): A mesh has no tetrahedrons, vertices or polygons.
- `NON_MANIFOLD_FACE` (`10`): Three or more tetrahedrons share one face.
- `DEGENERATE_TETRAHEDRON_TOO_SMALL` (`11`): The tetrahedron `first_index` names has a positive orientation determinant above 1e-15 and at most 1e-9, or a NaN one.
- `DEGENERATE_TETRAHEDRON_FLAT` (`12`): The tetrahedron `first_index` names has an orientation determinant of magnitude at most 1e-15.
- `DEGENERATE_TETRAHEDRON_INVERTED` (`13`): The tetrahedron `first_index` names is ordered right-handed: its orientation determinant is below -1e-15.
- `SCALE_OUT_OF_RANGE` (`14`): The length scale lies outside [0.001, 1,000].
- `DEGENERATE_REGION` (`15`): The polygon `second_index` names, of the material region `first_index` names, has fewer than 3 vertices or a zero normal.
- `TIME_WENT_BACKWARDS` (`16`): A step's time lies before the last step's time.
- `INVALID_WORKER_COUNT` (`17`): A worker count of 0.
- `CANCELLED` (`18`): The cancel flag stopped a tool.
- `OUTPUT_TOO_LARGE` (`19`): The output would hold more elements than 32-bit indices address, or, for [`autocage`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/tools/#autocage), the targets ask for triangles finer than the tool resolves.
- `DEGENERATE_POLYGON` (`20`): The polygon `first_index` names has a loop of fewer than 3 vertices, a zero normal or loops the triangulator cannot mesh.
- `NON_MANIFOLD_EDGE` (`21`): The edge between the vertices `first_index` and `second_index` borders three or more polygons.
- `NON_CLOSED_BOUNDARY` (`22`): The edge between the vertices `first_index` and `second_index` borders only one polygon.
- `COULD_NOT_CONVERGE` (`23`): The triangulation of a polygon mesh did not settle at any quality.
- `BAD_SCALES` (`24`): An anisotropy scale or direction is NaN.
- `MESHING_FAILED` (`25`): The mesher stopped without a mesh, or the maximum edge length is 0 or less.
- `NO_TETRAHEDRONS` (`26`): The mesh has no tetrahedron.
- `INVALID_CAGE` (`27`): The cage is not closed, does not face outward, or crosses itself.
- `NON_POSITIVE_THICKNESS` (`28`): The extrusion thickness is 0, negative or NaN.
- `NOT_ISOMORPHIC` (`29`): The two layers do not have the same vertices and faces.
- `UNKNOWN_VERTEX` (`30`): The face `first_index` names has a vertex past the end of the positions.
- `DUPLICATE_VERTEX` (`31`): The face `first_index` names uses one vertex at two corners.
- `MULTIPLE_BOUNDARIES` (`32`): The faces around the vertex `first_index` names form more than one fan.
- `DEGENERATE_FACE` (`33`): The face `first_index` names has a zero normal.
- `NULL_NORMAL` (`34`): The angle-weighted normals around the vertex `first_index` names cancel out.
- `EMPTY_INPUT` (`35`): No polygon has three or more corners, or all the vertices they use coincide.
- `STEP_LIMIT_REACHED` (`36`): The [`autocage`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/tools/#autocage) front did not close within its step cap.
- `INVALID_SPLINTER_CAGE` (`37`): A splinter cage polygon has fewer than 3 vertices, or a brick has 3 faces or fewer.
- `EMPTY_IMAGE` (`38`): The image width or height is 0.
- `NO_VERTICES` (`39`): The image has no vertex pixel, or none is left after the cleanup.
- `NO_CELLS` (`40`): The image has vertices but no closed cell.
- `ENDLESS_CYCLE` (`41`): A splinter face trace took more steps than there are vertices.
- `FACE_ALREADY_SET` (`42`): A splinter face trace met an edge side another face already holds.
- `SINGULAR_TRANSFORM` (`43`): The world transform has no inverse: its linear part is singular, or its inverse overflows.
- `LICENSE_REQUIRED` (`44`): No usable trial or license on this device: the trial ended, this device cannot have one, or the license was removed. It raises [`LicenseRequiredError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenserequirederror), whose message is the license status line, such as "Trial ended — Buy license", written to show the user as it is.
- `TRIAL_LIMIT_EXCEEDED` (`45`): The trial allows at most 2,500 tetrahedrons per scene and the call would go over. It raises [`TrialLimitExceededError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#triallimitexceedederror): `tetrahedrons` is the count that would take part, those of the scene's enabled objects (a disabled object does not count), `limit` the limit, and the message says both, such as "Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500".
- `LICENSE_NEEDS_ONLINE` (`46`): One online check is needed: the trial never started, the license went without a renewal for longer than it may run offline, or the clock is behind. The message is the license status line.
- `LICENSE_SERVICE_UNAVAILABLE` (`47`): The licensing service could not be reached (no network, a timeout, a busy service), refused this copy of the library, or gave an answer that did not verify; or online access is off in this process.
- `LICENSE_KEY_REJECTED` (`48`): The licensing service refused the license key: unknown, revoked or expired, of another product, or its seat is in use on another device; or the service takes no more devices.
- `LICENSE_STORAGE_FAILED` (`49`): The per-user license state could not be written; the message names its folder.

**See also** [Guide: Errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#errors) · [C `DeformableStatus`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformablestatus) · [Rust `ErrorKind`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#errorkind)

### Status.is_license

**Property** · `deformable.Status.is_license`

```python
@property
def is_license(self) -> bool
```

Whether the status is about the license of this device and user, rather than the call's arguments: its message is a status line or a licensing service's answer, written for the user as it is.

It is true for the six license statuses, from `LICENSE_REQUIRED` to `LICENSE_STORAGE_FAILED`, the ones that raise [`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror).

**Example**

```python
deformable.Status.TRIAL_LIMIT_EXCEEDED.is_license
# True
deformable.Status.INVALID_ARGUMENT.is_license
# False
```

**See also** [Rust `ErrorKind::is_license`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#errorkind-is_license)

## LicenseError

**Exception** · `deformable.LicenseError`

```python
class LicenseError(DeformableError)
```

The license of this device and user refused a call, or the licensing service could not be reached or refused the key: one of the six statuses whose [`Status.is_license`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-is_license) is true, [`LICENSE_REQUIRED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_required) to [`LICENSE_STORAGE_FAILED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_storage_failed).

Its message is written for the user as it is, such as "Trial ended — Buy license", so a host shows `message` alone, without the status name. [`LICENSE_REQUIRED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_required) and [`TRIAL_LIMIT_EXCEEDED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-trial_limit_exceeded) raise its subclasses [`LicenseRequiredError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenserequirederror) and [`TrialLimitExceededError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#triallimitexceedederror).

**Example**

```python
try:
    report = scene.step(1.0, substeps=10)
except deformable.TrialLimitExceededError as error:
    print(error.tetrahedrons, "over", error.limit)
except deformable.LicenseError as error:
    print(error.message)
```

**See also** [Guide: License errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#license-errors)

## LicenseRequiredError

**Exception** · `deformable.LicenseRequiredError`

```python
class LicenseRequiredError(LicenseError)
```

[`LICENSE_REQUIRED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_required): no usable trial or license on this device, because the trial ended, this device cannot have one, or the license was removed. The message is the license status line, such as "Trial ended — Buy license".

**See also** [Guide: License errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#license-errors)

## TrialLimitExceededError

**Exception** · `deformable.TrialLimitExceededError`

```python
class TrialLimitExceededError(LicenseError)
```

[`TRIAL_LIMIT_EXCEEDED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-trial_limit_exceeded): the trial allows at most `limit` tetrahedrons per scene, and with the call `tetrahedrons` would take part, those of the scene's enabled objects (a disabled object does not count). The message says both, such as "Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500".

**See also** [Guide: License errors](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#license-errors)

### TrialLimitExceededError.tetrahedrons

**Property** · `deformable.TrialLimitExceededError.tetrahedrons`

```python
@property
def tetrahedrons(self) -> int
```

The tetrahedrons the scene would have held: the error's `first_index`.

### TrialLimitExceededError.limit

**Property** · `deformable.TrialLimitExceededError.limit`

```python
@property
def limit(self) -> int
```

The most tetrahedrons a trial scene may hold, 2,500: the error's `second_index`.

## library_version

**Function** · `deformable.library_version`

```python
def library_version() -> str
```

The version of the loaded shared library, as `major.minor.patch`. It matches `deformable.__version__` when the package and the library come from the same release.

**Raises**

[`LibraryNotFoundError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#librarynotfounderror) when no shared library is found; this call loads it when no call has yet.

**Example**

```python
version = deformable.library_version()
len(version.split("."))
# 3
```

**See also** [Guide: Versions](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#versions) · [C `deformable_version`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformable_version) · [Rust `version`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#version)

## LibraryNotFoundError

**Exception** · `deformable.LibraryNotFoundError`

```python
class LibraryNotFoundError(OSError)
```

No shared library was found. The package loads it the first time a call needs it, from the first of these places that holds it: the file the `DEFORMABLE_LIBRARY` environment variable names, the package directory, where a distribution of the package places it, then `target/release` of the Cargo workspace the package sits in, where a source checkout builds it. The message lists the places searched.

**See also** [Guide: How the package finds the library](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#how-the-package-finds-the-library)

## CancelFlag

**Class** · `deformable.CancelFlag`

```python
class CancelFlag:
    def __init__(self) -> None
```

A thread-safe cancel flag, not set when created: set from any thread, it stops a running tool, which raises [`DeformableError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#deformableerror) with the status [`CANCELLED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-cancelled), or a running step, which reports [`StepOutcome.CANCELLED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/scene/#stepoutcome-cancelled).

[`Scene.step`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/scene/#scene-step), [`triangulate`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/tools/#triangulate), [`tetrahedralize`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/tools/#tetrahedralize) and [`autocage`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/tools/#autocage) take one and stop at their next check once it is set: a tool at once when it is already set, a step after its first substep. The flag stays set until it is cleared, and one flag can serve several calls at once. Library calls release the global interpreter lock, so one Python thread can set the flag while another runs a step or a tool that was given it.

It works as a context manager: a `with` block calls `close()` when it ends.

**Example**

```python
with deformable.CancelFlag() as cancel:
    cancel.set()
    try:
        deformable.triangulate(polygons, cancel=cancel)
    except deformable.DeformableError as error:
        print(error.status.name)
# CANCELLED
```

**See also** [Guide: Cancel a long call](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/types-and-errors/#cancel-a-long-call) · [C `DeformableCancelFlag`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformablecancelflag) · [Rust `CancelFlag`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#cancelflag)

### CancelFlag.set

**Method** · `deformable.CancelFlag.set`

```python
def set(self) -> None
```

Sets the flag; a call that reads it stops at its next check.

**Raises**

`ValueError` when the flag is closed.

**See also** [C `deformable_cancel_flag_set`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformable_cancel_flag_set) · [Rust `CancelFlag::set`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#cancelflag-set)

### CancelFlag.clear

**Method** · `deformable.CancelFlag.clear`

```python
def clear(self) -> None
```

Clears the flag, so it can be used again.

**Raises**

`ValueError` when the flag is closed.

### CancelFlag.is_set

**Method** · `deformable.CancelFlag.is_set`

```python
def is_set(self) -> bool
```

True while the flag is set.

**Raises**

`ValueError` when the flag is closed.

**See also** [C `deformable_cancel_flag_is_set`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformable_cancel_flag_is_set) · [Rust `CancelFlag::is_set`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/errors/#cancelflag-is_set)

### CancelFlag.closed

**Property** · `deformable.CancelFlag.closed`

```python
@property
def closed(self) -> bool
```

True once the handle has been destroyed.

### CancelFlag.close

**Method** · `deformable.CancelFlag.close`

```python
def close(self) -> None
```

Destroys the handle once the calls in flight on it end; later calls on the object raise ValueError. Closing twice does nothing.

**See also** [C `deformable_cancel_flag_destroy`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/errors/#deformable_cancel_flag_destroy)
