﻿---
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.3.0/api-references/rust/errors/
---

# Errors – Rust API Reference – Deformable v0.3.0

What a failed call reports: the [`ErrorKind`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind) that names what went wrong, and the [`Error`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#error) that carries it. Then the library version, and the [`CancelFlag`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#cancelflag) that stops a long call from another thread.

## Error

**Struct** · `deformable::Error`

```rust
pub struct Error { /* private fields */ }
```

A failed call: what went wrong, 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 Free
license's tetrahedron count and limit, as the [`ErrorKind`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind) variant says; they are 0 when it names none. Its `Display` is
the message. Arguments the C interface cannot carry are refused by the crate itself, before the library is called,
with the same type and indices of 0.

**Implements** `Clone` · `Debug` · `Display` · `Eq` · `PartialEq` · `std::error::Error` · `Send` · `Sync`

**Example**

```rust
let error = scene.set_worker_count(0).unwrap_err();
assert_eq!(error.kind(), ErrorKind::InvalidWorkerCount);
assert_eq!(error.first_index(), 0);
println!("{error}");
```

**See also** [Guide: The error type](https://help.tangerina.io/deformable/v0.3.0/user-guides/rust/errors/#the-error-type) · [C `DeformableErrorDetails`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/errors/#deformableerrordetails) · [Python `DeformableError`](https://help.tangerina.io/deformable/v0.3.0/api-references/python/errors/#deformableerror)

### Error::kind

**Method** · `deformable::Error::kind`

```rust
pub fn kind(&self) -> ErrorKind
```

What went wrong.

### Error::first_index

**Method** · `deformable::Error::first_index`

```rust
pub fn first_index(&self) -> u32
```

The first index the failure names (the tetrahedron, region, polygon, face, vertex or edge's first vertex, or
the tetrahedrons a Free license scene would simulate), or 0.

### Error::second_index

**Method** · `deformable::Error::second_index`

```rust
pub fn second_index(&self) -> u32
```

The second index the failure names (the region's polygon, the edge's second vertex, or the Free license's
tetrahedron limit), or 0.

### Error::message

**Method** · `deformable::Error::message`

```rust
pub fn message(&self) -> &str
```

The description of the failure, in English: the library's, or the crate's own for an argument it refused. A
license kind's message is written to show the user as it is.

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

## ErrorKind

**Enum** · `deformable::ErrorKind`

```rust
pub enum ErrorKind {
    NullPointer,
    InvalidArgument,
    Panicked,
    IndexOutOfRange,
    UnknownMaterial,
    UnknownObject,
    LengthMismatch,
    NonFiniteValue,
    EmptyMesh,
    NonManifoldFace,
    DegenerateTetrahedron(DegenerateKind),
    ScaleOutOfRange,
    DegenerateRegion,
    TimeWentBackwards,
    InvalidWorkerCount,
    Cancelled,
    OutputTooLarge,
    DegeneratePolygon,
    NonManifoldEdge,
    NonClosedBoundary,
    CouldNotConverge,
    BadScales,
    MeshingFailed,
    NoTetrahedrons,
    InvalidCage,
    NonPositiveThickness,
    NotIsomorphic,
    UnknownVertex,
    DuplicateVertex,
    MultipleBoundaries,
    DegenerateFace,
    NullNormal,
    EmptyInput,
    StepLimitReached,
    InvalidSplinterCage,
    EmptyImage,
    NoVertices,
    NoCells,
    EndlessCycle,
    FaceAlreadySet,
    SingularTransform,
    TetrahedronLimitExceeded,
    LicenseServiceUnavailable,
    LicenseKeyRejected,
    LicenseStorageFailed,
    Unrecognized(i32),
}
```

What went wrong: one kind per failure status of the library, the three degenerate tetrahedron statuses in one kind
with a [`DegenerateKind`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/mesh-checks/#degeneratekind).

The indices of the [`Error`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#error) name the element a kind concerns, as each variant says; they are 0 when it names
none. The enum is `#[non_exhaustive]`, since a newer library can add statuses: a status this crate does not know
comes as [`Unrecognized`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-unrecognized).

**Values**

- `NullPointer`: A required pointer was null. The safe API never passes one; seeing it means a defect in this crate.
- `InvalidArgument`: An argument the library cannot read: an undefined enumeration value, an array larger than the address space,
  or a material preset name the library does not ship. The license calls give it for text that is no license
  key, a Developer license key that does not verify, another Standard key while one is stored, another Developer
  key once one is set, and a Standard key in a program on a Developer license.
- `Panicked`: The library panicked; the handles the call used should be dropped.
- `IndexOutOfRange`: An index points past the end of the list it indexes; for the polygon tools the first index names the polygon.
- `UnknownMaterial`: A material handle names no material of the scene.
- `UnknownObject`: An object handle names no object of the scene, or a removed one.
- `LengthMismatch`: A list does not have the length its partner requires.
- `NonFiniteValue`: A position or parameter is NaN or infinite.
- `EmptyMesh`: A mesh has no tetrahedrons, vertices or polygons.
- `NonManifoldFace`: Three or more tetrahedrons share one face.
- `DegenerateTetrahedron` ([`DegenerateKind`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/mesh-checks/#degeneratekind)): The tetrahedron the first index names fails the quality check: its orientation determinant is not above 1e-9.
  The [`DegenerateKind`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/mesh-checks/#degeneratekind) says whether it is too small, flat or inverted.
- `ScaleOutOfRange`: The length scale lies outside \[0.001, 1,000\].
- `DegenerateRegion`: The polygon the second index names, of the material region the first index names, has fewer than 3 vertices
  or a zero normal.
- `TimeWentBackwards`: A step's time lies before the last step's time.
- `InvalidWorkerCount`: A worker count of 0.
- `Cancelled`: The cancel flag stopped a tool.
- `OutputTooLarge`: The output would hold more elements than 32-bit indices address, or, for autocage, the targets ask for
  triangles finer than the tool resolves.
- `DegeneratePolygon`: The polygon the first index names has a loop of fewer than 3 vertices, a zero normal or loops the
  triangulator cannot mesh.
- `NonManifoldEdge`: The edge between the vertices the first and second index name borders three or more polygons.
- `NonClosedBoundary`: The edge between the vertices the first and second index name borders only one polygon.
- `CouldNotConverge`: The triangulation of a polygon mesh did not settle at any quality.
- `BadScales`: An anisotropy scale or direction is NaN.
- `MeshingFailed`: The mesher stopped without a mesh, or the maximum edge length is 0 or less.
- `NoTetrahedrons`: The mesh has no tetrahedron.
- `InvalidCage`: The cage is not closed, does not face outward, or crosses itself.
- `NonPositiveThickness`: The extrusion thickness is 0, negative or NaN.
- `NotIsomorphic`: The two layers do not have the same vertices and faces.
- `UnknownVertex`: The face the first index names has a vertex past the end of the positions.
- `DuplicateVertex`: The face the first index names uses one vertex at two corners.
- `MultipleBoundaries`: The faces around the vertex the first index names form more than one fan.
- `DegenerateFace`: The face the first index names has a zero normal.
- `NullNormal`: The angle-weighted normals around the vertex the first index names cancel out.
- `EmptyInput`: No polygon has three or more corners, or all the vertices they use coincide.
- `StepLimitReached`: The autocage front did not close within its step cap.
- `InvalidSplinterCage`: A splinter cage polygon has fewer than 3 vertices, or a brick has 3 faces or fewer.
- `EmptyImage`: The image width or height is 0.
- `NoVertices`: The image has no vertex pixel, or none is left after the cleanup.
- `NoCells`: The image has vertices but no closed cell.
- `EndlessCycle`: A splinter face trace took more steps than there are vertices.
- `FaceAlreadySet`: A splinter face trace met an edge side another face already holds.
- `SingularTransform`: The world transform has no inverse: its linear part is singular, or its inverse overflows.
- `TetrahedronLimitExceeded`: Under the Free license, adding the object would take the scene past the 2,500 tetrahedrons one scene
  simulates: the first index is the tetrahedrons the scene would simulate with it (those of the objects it
  simulates now, and the object's), the second the limit. Nothing is created and the rest of the scene runs. The
  message says both numbers, such as "Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500
  per scene".
- `LicenseServiceUnavailable`: 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.
- `LicenseKeyRejected`: The license key was refused. The licensing service refused the Standard 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
  Developer key was revoked, is a trial key that ended, covers only versions released before this one, or was
  given inside a plugin host.
- `LicenseStorageFailed`: The per-user license store could not be written; the message names its folder.
- `Unrecognized` (`i32`): A code this crate does not know, from a newer library: a status, a step outcome or a mesh issue kind.

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `Hash` · `PartialEq` · `Send` · `Sync`

**See also** [Guide: Error kinds](https://help.tangerina.io/deformable/v0.3.0/user-guides/rust/errors/#error-kinds) · [C `DeformableStatus`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/errors/#deformablestatus) · [Python `Status`](https://help.tangerina.io/deformable/v0.3.0/api-references/python/errors/#status)

### ErrorKind::is_license

**Method** · `deformable::ErrorKind::is_license`

```rust
pub fn is_license(self) -> bool
```

Whether the failure is about the license of this program rather than the call's arguments; its message is then
a status line, the licensing service's answer or why a Developer key was refused, written to show the user as
it is.

It is true for the four license kinds, from [`TetrahedronLimitExceeded`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-tetrahedronlimitexceeded) to
[`LicenseStorageFailed`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind-licensestoragefailed).

**Example**

```rust
use deformable::ErrorKind;

assert!(ErrorKind::TetrahedronLimitExceeded.is_license());
assert!(!ErrorKind::InvalidArgument.is_license());
```

**See also** [Python `Status.is_license`](https://help.tangerina.io/deformable/v0.3.0/api-references/python/errors/#status-is_license)

## version

**Function** · `deformable::version`

```rust
pub fn version() -> &'static str
```

The version of the linked libdeformable, as `major.minor.patch`. It matches the crate's version when the two come
from the same release.

**Example**

```rust
let version = deformable::version();
assert_eq!(version.split('.').count(), 3);
println!("libdeformable {version}");
```

**See also** [C `deformable_version`](https://help.tangerina.io/deformable/v0.3.0/api-references/c/errors/#deformable_version) · [Python `library_version`](https://help.tangerina.io/deformable/v0.3.0/api-references/python/errors/#library_version)

## CancelFlag

**Struct** · `deformable::CancelFlag`

```rust
pub struct CancelFlag { /* private fields */ }
```

A cancel flag: set from any thread, it stops a running tool with [`ErrorKind::Cancelled`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/errors/#errorkind) or a
running step with [`StepOutcome::Cancelled`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/scene/#stepoutcome).

[`Scene::step`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/scene/#scene-step), [`triangulate`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/tools/#triangulate),
[`tetrahedralize`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/tools/#tetrahedralize) and [`autocage`](https://help.tangerina.io/deformable/v0.3.0/api-references/rust/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. Every call on it is thread-safe, so a
host's interface thread can set it through a shared reference while a step or a tool reads it on another thread.

**Implements** `Debug` · `Default` · `Drop` · `Send` · `Sync`

**Example**

```rust
let cancel = CancelFlag::new();
cancel.set(true);
let parameters = TriangulateParameters::default();
let result = triangulate(&polygons, &[], &parameters, Some(&cancel));
assert_eq!(result.unwrap_err().kind(), ErrorKind::Cancelled);
```

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

### CancelFlag::new

**Associated function** · `deformable::CancelFlag::new`

```rust
pub fn new() -> Self
```

A flag, not set. Dropping it frees it; a call that borrows it keeps it alive until the call ends.

Panics when the library fails inside and cannot create the flag.

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

### CancelFlag::set

**Method** · `deformable::CancelFlag::set`

```rust
pub fn set(&self, cancelled: bool)
```

Sets (`true`) or clears (`false`) the flag; a call that reads it stops at its next check.

**Parameters**

- `cancelled` (`bool`): `true` sets the flag, `false` clears it so the flag can be used again.

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

### CancelFlag::is_set

**Method** · `deformable::CancelFlag::is_set`

```rust
pub fn is_set(&self) -> bool
```

True when the flag is set.

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