﻿---
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.8.0/api-references/python/errors/
---

# Errors – Python API Reference – Deformable v0.8.0

What a failed call reports: the [`Status`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status) that names what went wrong, and the [`DeformableError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#deformableerror) that carries it. Then the library version, and the [`CancelFlag`](https://help.tangerina.io/deformable/v0.8.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 Free's tetrahedron count and limit, as each [`Status`](https://help.tangerina.io/deformable/v0.8.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.8.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.8.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 a Free scene would simulate), or 0. Default `0`.
- `second_index` (`int`): The second element index the status names (the region's polygon, the edge's second vertex, or Free'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.8.0/user-guides/python/types-and-errors/#deformableerror) · [C `DeformableErrorDetails`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformableerrordetails) · [Rust `Error`](https://help.tangerina.io/deformable/v0.8.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
    TETRAHEDRON_LIMIT_EXCEEDED = 44
    LICENSE_SERVICE_UNAVAILABLE = 45
    LICENSE_KEY_REJECTED = 46
    LICENSE_STORAGE_FAILED = 47
    LICENSE_SIGN_IN_FAILED = 48
```

What a failed library call reports, in [`DeformableError.status`](https://help.tangerina.io/deformable/v0.8.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.8.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.8.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, an Application license key that does not verify, another Standalone key while one is stored, a Standalone key while a Standalone subscription is signed in or a sign-in while a key is stored or another sign-in has not ended, a wait for or a take-over of a sign-in that is not there, another Application key once one is set, and a Standalone key or a sign-in in a program on an Application license.
- `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.8.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.8.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.
- `TETRAHEDRON_LIMIT_EXCEEDED` (`44`): Under Free, adding the object would take the scene past the 2,500 tetrahedrons one scene simulates. It raises [`TetrahedronLimitExceededError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#tetrahedronlimitexceedederror): `tetrahedrons` is the count the scene would simulate with it (those of the objects it simulates now, and the object's), `limit` the limit, and the message says both, such as "Free: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene". Nothing is created and the rest of the scene runs.
- `LICENSE_SERVICE_UNAVAILABLE` (`45`): The licensing service could not be reached (no network, a timeout, a busy service), did not answer, or gave an answer that did not verify or that this device's clock contradicts; or online access is off in this process.
- `LICENSE_KEY_REJECTED` (`46`): The license key was refused. The licensing service refused the Standalone key: it does not exist, was revoked or refunded, is not for Deformable, every seat of the license is in use, or this device was removed. Or the Application key was revoked, is a trial key that ended, covers only versions released before this one, or was given inside a plugin host.
- `LICENSE_STORAGE_FAILED` (`47`): The per-user license store could not be written; the message names its folder.
- `LICENSE_SIGN_IN_FAILED` (`48`): The sign-in to a Standalone subscription failed: it was denied, its code is no longer valid, this version of the library may not sign in, or the licensing service could not read the request.

**See also** [Guide: Errors](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/types-and-errors/#errors) · [C `DeformableStatus`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablestatus) · [Rust `ErrorKind`](https://help.tangerina.io/deformable/v0.8.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 program, rather than the call's arguments: its message is a status line, a licensing service's answer or why an Application key was refused, written for the user as it is.

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

**Example**

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

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

## LicenseError

**Exception** · `deformable.LicenseError`

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

A license failure: an object past Free's limit, the licensing service could not be reached, a license key was refused, or a sign-in failed. One of the five statuses whose [`Status.is_license`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status-is_license) is true, [`TETRAHEDRON_LIMIT_EXCEEDED`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status-tetrahedron_limit_exceeded) to [`LICENSE_SIGN_IN_FAILED`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status-license_sign_in_failed).

Its message is written for the user as it is, such as "This license key was revoked", so a host shows `message` alone, without the status name. [`TETRAHEDRON_LIMIT_EXCEEDED`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status-tetrahedron_limit_exceeded) raises its subclass [`TetrahedronLimitExceededError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#tetrahedronlimitexceedederror).

**Example**

```python
try:
    handle = scene.add_object(mesh, material)
except deformable.TetrahedronLimitExceededError 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.8.0/user-guides/python/types-and-errors/#license-errors)

## TetrahedronLimitExceededError

**Exception** · `deformable.TetrahedronLimitExceededError`

```python
class TetrahedronLimitExceededError(LicenseError)
```

[`TETRAHEDRON_LIMIT_EXCEEDED`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status-tetrahedron_limit_exceeded): under Free a scene simulates at most `limit` tetrahedrons, and with the object it would simulate `tetrahedrons`. The object is not created and the rest of the scene runs. The message says both, such as "Free: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene".

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

### TetrahedronLimitExceededError.tetrahedrons

**Property** · `deformable.TetrahedronLimitExceededError.tetrahedrons`

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

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

### TetrahedronLimitExceededError.limit

**Property** · `deformable.TetrahedronLimitExceededError.limit`

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

The most tetrahedrons a Free scene simulates, 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.8.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.8.0/user-guides/python/types-and-errors/#versions) · [C `deformable_version`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformable_version) · [Rust `version`](https://help.tangerina.io/deformable/v0.8.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.8.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.8.0/api-references/python/errors/#deformableerror) with the status [`CANCELLED`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#status-cancelled), or a running step, which reports [`StepOutcome.CANCELLED`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/#stepoutcome-cancelled).

[`Scene.step`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/#scene-step), [`triangulate`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#triangulate), [`tetrahedralize`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/#tetrahedralize) and [`autocage`](https://help.tangerina.io/deformable/v0.8.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.8.0/user-guides/python/types-and-errors/#cancel-a-long-call) · [C `DeformableCancelFlag`](https://help.tangerina.io/deformable/v0.8.0/api-references/c/errors/#deformablecancelflag) · [Rust `CancelFlag`](https://help.tangerina.io/deformable/v0.8.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.8.0/api-references/c/errors/#deformable_cancel_flag_set) · [Rust `CancelFlag::set`](https://help.tangerina.io/deformable/v0.8.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.8.0/api-references/c/errors/#deformable_cancel_flag_is_set) · [Rust `CancelFlag::is_set`](https://help.tangerina.io/deformable/v0.8.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.8.0/api-references/c/errors/#deformable_cancel_flag_destroy)
