﻿---
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.2.0/api-references/c/errors/
---

# Errors – C API Reference – Deformable v0.2.0

What a failed call reports: the [`DeformableStatus`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablestatus) that names what went wrong, and the [`DeformableErrorDetails`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformableerrordetails) that carries it. Then the library version, and the [`DeformableCancelFlag`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablecancelflag) that stops a long call from another thread.

## DeformableErrorDetails

**Struct** · `deformable.h`

```c
typedef struct DeformableErrorDetails {
    DeformableStatus status;
    uint32_t first_index;
    uint32_t second_index;
} DeformableErrorDetails;
```

The status and indices of the last failed call on the calling thread, as [`deformable_last_error_details`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformable_last_error_details) writes them;
[`deformable_last_error_message`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformable_last_error_message) gives its message.

The indices name the tetrahedron, region, polygon, face, vertex or edge the failure concerns, or the trial's
tetrahedron count and limit, as each [`DeformableStatus`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablestatus) code says; they are 0 when it names none.

**Fields**

- `status` ([`DeformableStatus`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablestatus)): The status the call returned; [`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablestatus-deformable_status_ok) when the latest call succeeded.
- `first_index` (`uint32_t`): The first index the failure 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.
- `second_index` (`uint32_t`): The second index the failure names (the region's polygon, the edge's second vertex, or the trial's tetrahedron
  limit), or 0.

**See also** [Guide: Status codes and the last error](https://help.tangerina.io/deformable/v0.2.0/user-guides/c/memory-and-errors/#status-codes-and-the-last-error) · [Rust `Error`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#error) · [Python `DeformableError`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/errors/#deformableerror)

## DeformableStatus

**Enum** · `deformable.h`

```c
typedef int32_t DeformableStatus;
```

The outcome of a call: `DEFORMABLE_STATUS_OK` (0) on success, a positive `DEFORMABLE_STATUS_*` code otherwise.

The indices of the last error ([`DeformableErrorDetails`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformableerrordetails)) name the element a status concerns, as each code says; they
are 0 when it names none. A newer library can add statuses, so a host treats a code this header does not define as
a failure too.

**Values**

- `DEFORMABLE_STATUS_OK` (`0`): The call succeeded.
- `DEFORMABLE_STATUS_NULL_POINTER` (`1`): A required pointer argument is `NULL`, or an array pointer is `NULL` while its count is not 0.
- `DEFORMABLE_STATUS_INVALID_ARGUMENT` (`2`): An argument the library cannot read: an undefined enumeration value, a misaligned pointer, an array larger than the
  address space or a material preset name the library does not ship. The license functions give it for a timeout of 0,
  a key that is not UTF-8 or 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.
- `DEFORMABLE_STATUS_PANICKED` (`3`): The library panicked; the handles the call used should be destroyed.
- `DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE` (`4`): An index points past the end of the list it indexes; the first index names the polygon for the polygon tools.
- `DEFORMABLE_STATUS_UNKNOWN_MATERIAL` (`5`): A material handle names no material of the scene.
- `DEFORMABLE_STATUS_UNKNOWN_OBJECT` (`6`): An object handle names no object of the scene, or a removed one.
- `DEFORMABLE_STATUS_LENGTH_MISMATCH` (`7`): A list does not have the length its partner requires.
- `DEFORMABLE_STATUS_NON_FINITE_VALUE` (`8`): A position or parameter is NaN or infinite.
- `DEFORMABLE_STATUS_EMPTY_MESH` (`9`): A mesh has no tetrahedrons, vertices or polygons.
- `DEFORMABLE_STATUS_NON_MANIFOLD_FACE` (`10`): Three or more tetrahedrons share one face.
- `DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_TOO_SMALL` (`11`): Tetrahedron `first_index` has a positive orientation determinant above 1e-15 and at most 1e-9, or a NaN one.
- `DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_FLAT` (`12`): Tetrahedron `first_index` has an orientation determinant of magnitude at most 1e-15.
- `DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_INVERTED` (`13`): Tetrahedron `first_index` is ordered right-handed (orientation determinant below -1e-15).
- `DEFORMABLE_STATUS_SCALE_OUT_OF_RANGE` (`14`): The length scale lies outside \[0.001, 1,000\].
- `DEFORMABLE_STATUS_DEGENERATE_REGION` (`15`): Polygon `second_index` of material region `first_index` has fewer than 3 vertices or a zero normal.
- `DEFORMABLE_STATUS_TIME_WENT_BACKWARDS` (`16`): A step's time lies before the last step's time.
- `DEFORMABLE_STATUS_INVALID_WORKER_COUNT` (`17`): A worker count of 0.
- `DEFORMABLE_STATUS_CANCELLED` (`18`): The cancel flag stopped a tool.
- `DEFORMABLE_STATUS_OUTPUT_TOO_LARGE` (`19`): The output would hold more elements than 32-bit indices address, or, for [`deformable_autocage`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/tools/#deformable_autocage), the targets ask for
  triangles finer than the tool resolves.
- `DEFORMABLE_STATUS_DEGENERATE_POLYGON` (`20`): Polygon `first_index` has a loop of fewer than 3 vertices, a zero normal or loops the triangulator cannot mesh.
- `DEFORMABLE_STATUS_NON_MANIFOLD_EDGE` (`21`): The edge between vertices `first_index` and `second_index` borders three or more polygons.
- `DEFORMABLE_STATUS_NON_CLOSED_BOUNDARY` (`22`): The edge between vertices `first_index` and `second_index` borders only one polygon.
- `DEFORMABLE_STATUS_COULD_NOT_CONVERGE` (`23`): The triangulation of a polygon mesh did not settle at any quality.
- `DEFORMABLE_STATUS_BAD_SCALES` (`24`): An anisotropy scale or direction is NaN.
- `DEFORMABLE_STATUS_MESHING_FAILED` (`25`): The mesher stopped without a mesh, or the maximum edge length is 0 or less.
- `DEFORMABLE_STATUS_NO_TETRAHEDRONS` (`26`): The mesh has no tetrahedron.
- `DEFORMABLE_STATUS_INVALID_CAGE` (`27`): The cage is not closed, does not face outward, or crosses itself.
- `DEFORMABLE_STATUS_NON_POSITIVE_THICKNESS` (`28`): The extrusion thickness is 0, negative or NaN.
- `DEFORMABLE_STATUS_NOT_ISOMORPHIC` (`29`): The two layers do not have the same vertices and faces.
- `DEFORMABLE_STATUS_UNKNOWN_VERTEX` (`30`): Face `first_index` names a vertex past the end of the positions.
- `DEFORMABLE_STATUS_DUPLICATE_VERTEX` (`31`): Face `first_index` uses one vertex at two corners.
- `DEFORMABLE_STATUS_MULTIPLE_BOUNDARIES` (`32`): The faces around vertex `first_index` form more than one fan.
- `DEFORMABLE_STATUS_DEGENERATE_FACE` (`33`): Face `first_index` has a zero normal.
- `DEFORMABLE_STATUS_NULL_NORMAL` (`34`): The angle-weighted normals around vertex `first_index` cancel out.
- `DEFORMABLE_STATUS_EMPTY_INPUT` (`35`): No polygon has three or more corners, or all the vertices they use coincide.
- `DEFORMABLE_STATUS_STEP_LIMIT_REACHED` (`36`): The autocage front did not close within its step cap.
- `DEFORMABLE_STATUS_INVALID_SPLINTER_CAGE` (`37`): A splinter cage polygon has fewer than 3 vertices, or a brick has 3 faces or fewer.
- `DEFORMABLE_STATUS_EMPTY_IMAGE` (`38`): The image width or height is 0.
- `DEFORMABLE_STATUS_NO_VERTICES` (`39`): The image has no vertex pixel, or none is left after the cleanup.
- `DEFORMABLE_STATUS_NO_CELLS` (`40`): The image has vertices but no closed cell.
- `DEFORMABLE_STATUS_ENDLESS_CYCLE` (`41`): A splinter face trace took more steps than there are vertices.
- `DEFORMABLE_STATUS_FACE_ALREADY_SET` (`42`): A splinter face trace met an edge side another face already holds.
- `DEFORMABLE_STATUS_SINGULAR_TRANSFORM` (`43`): The world transform has no inverse: its linear part is singular, or its inverse overflows.
- `DEFORMABLE_STATUS_LICENSE_REQUIRED` (`44`): No usable trial or license: the Standard trial ended, this device cannot have one, or the Standard license was
  removed; or the Developer trial key ended. The message is the license status line, such as "Standard trial ended —
  Buy license", written to show the user as it is.
- `DEFORMABLE_STATUS_TRIAL_LIMIT_EXCEEDED` (`45`): The Standard trial allows at most 2,500 tetrahedrons per scene and this call would go over: `first_index` is the
  tetrahedrons that would take part, those of the scene's enabled objects (a disabled object does not count),
  `second_index` the limit. The message says both numbers, such as "Trial limit: this would simulate 3,000 tetrahedrons;
  the trial allows 2,500".
- `DEFORMABLE_STATUS_LICENSE_NEEDS_ONLINE` (`46`): One online check is needed: the Standard trial never started, the Standard license went without a renewal for longer
  than it may run offline, or the clock is behind. The message is the license status line.
- `DEFORMABLE_STATUS_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.
- `DEFORMABLE_STATUS_LICENSE_KEY_REJECTED` (`48`): The license key was refused. The licensing service refused the Standard key: unknown, revoked or expired, of another
  product, or its seat is in use on another device; or the service takes no more devices. Or the Developer key was
  revoked, is a trial key that ended, or was given inside a plugin host, where only a Standard license works.
- `DEFORMABLE_STATUS_LICENSE_STORAGE_FAILED` (`49`): The per-user license state could not be written; the message names its folder.

**See also** [Guide: The status codes](https://help.tangerina.io/deformable/v0.2.0/user-guides/c/memory-and-errors/#the-status-codes) · [Rust `ErrorKind`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind) · [Python `Status`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/errors/#status)

## deformable_last_error_message

**Function** · `deformable.h`

```c
const char *deformable_last_error_message(void);
```

The message of the last failed call on the calling thread, as a NUL-terminated UTF-8 string in English; empty when
the latest status-returning call on this thread succeeded. A license status's message is written to show the user
as it is.

The string is owned by the library and stays valid until the next status-returning call on the same thread; copy it
to keep it longer. This call itself never changes the last error.

**Example**

```c
if (deformable_scene_set_worker_count(scene, 0))
    puts(deformable_last_error_message());
```

**See also** [Guide: Status codes and the last error](https://help.tangerina.io/deformable/v0.2.0/user-guides/c/memory-and-errors/#status-codes-and-the-last-error) · [Rust `Error::message`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#error-message)

## deformable_last_error_details

**Function** · `deformable.h`

```c
DeformableStatus deformable_last_error_details(
    DeformableErrorDetails *details);
```

Writes the status and indices of the last failed call on the calling thread to `details`; the status is
[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablestatus-deformable_status_ok) when the latest status-returning call on this thread succeeded.

Unlike every other call that returns a status, this one leaves the last error as it is, so a failure it reports (a
`NULL` `details`) is returned but not recorded.

**Parameters**

- `details` ([`DeformableErrorDetails *`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformableerrordetails)): Out. Receives the status and the two indices.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.2.0/api-references/c/overview/#conventions) describe.

**Example**

```c
DeformableStatus status =
    deformable_scene_set_worker_count(scene, 0);
DeformableErrorDetails details;
CHECK(deformable_last_error_details(&details));
// details.status is status; this status names no element.
if (details.status == status && details.first_index == 0)
    puts(deformable_last_error_message());
```

**See also** [Guide: Status codes and the last error](https://help.tangerina.io/deformable/v0.2.0/user-guides/c/memory-and-errors/#status-codes-and-the-last-error)

## deformable_last_error_clear

**Function** · `deformable.h`

```c
DeformableStatus deformable_last_error_clear(void);
```

Clears the last error of the calling thread, so that the next failure is the only one reported. Any other call
that returns a status clears it too when it succeeds, except [`deformable_last_error_details`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformable_last_error_details).

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.2.0/api-references/c/overview/#conventions) describe.

**Example**

```c
// A count of 0 is refused, which leaves a last error.
DeformableStatus status =
    deformable_scene_set_worker_count(scene, 0);
CHECK(deformable_last_error_clear());
DeformableErrorDetails details;
CHECK(deformable_last_error_details(&details));
puts(details.status != status ? "cleared" : "kept"); // cleared
```

**See also** [Guide: Status codes and the last error](https://help.tangerina.io/deformable/v0.2.0/user-guides/c/memory-and-errors/#status-codes-and-the-last-error)

## deformable_version

**Function** · `deformable.h`

```c
const char *deformable_version(void);
```

The library version, as `major.minor.patch`, in a static NUL-terminated string the host never frees.

**Example**

```c
const char *version = deformable_version();
puts(version);
```

**See also** [Rust `version`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#version) · [Python `library_version`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/errors/#library_version)

## DeformableCancelFlag

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableCancelFlag DeformableCancelFlag;
```

A cancel flag: set from any thread, it stops a running tool with [`DEFORMABLE_STATUS_CANCELLED`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablestatus-deformable_status_cancelled) or a running step with
[`DEFORMABLE_STEP_OUTCOME_CANCELLED`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformablestepoutcome-deformable_step_outcome_cancelled).

[`deformable_scene_step`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_step), [`deformable_triangulate`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/tools/#deformable_triangulate), [`deformable_tetrahedralize`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/tools/#deformable_tetrahedralize) and [`deformable_autocage`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/tools/#deformable_autocage) take one, or
`NULL` for none, 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 while a step or a tool reads it on another thread.

**Example**

```c
DeformableCancelFlag *cancel = NULL;
CHECK(deformable_cancel_flag_create(&cancel));
// Set before the call, the tool stops at once.
CHECK(deformable_cancel_flag_set(cancel, 1));
DeformableTriangulateParameters parameters;
CHECK(deformable_triangulate_parameters_default(&parameters));
DeformableTriangulation *result = NULL;
DeformableStatus status = deformable_triangulate(&polygons, NULL, 0,
                                                 &parameters, cancel,
                                                 &result);
puts(status == DEFORMABLE_STATUS_CANCELLED ? "cancelled" : "ran");
deformable_cancel_flag_destroy(cancel);
```

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

### deformable_cancel_flag_create

**Function** · `deformable.h`

```c
DeformableStatus deformable_cancel_flag_create(
    DeformableCancelFlag **flag);
```

Creates a cancel flag, not set, and writes its handle to `flag`.

**Parameters**

- `flag` ([`DeformableCancelFlag **`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablecancelflag)): Out. Receives a new handle; free it with [`deformable_cancel_flag_destroy`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformable_cancel_flag_destroy) once no call uses it.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.2.0/api-references/c/overview/#conventions) describe.

**See also** [Rust `CancelFlag::new`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#cancelflag-new)

### deformable_cancel_flag_destroy

**Function** · `deformable.h`

```c
void deformable_cancel_flag_destroy(DeformableCancelFlag *flag);
```

Destroys a cancel flag; `NULL` is ignored. No call, on any thread, may be using it.

**Parameters**

- `flag` ([`DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablecancelflag)): The flag to destroy, or `NULL`.

**See also** [Python `CancelFlag.close`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/errors/#cancelflag-close)

### deformable_cancel_flag_set

**Function** · `deformable.h`

```c
DeformableStatus deformable_cancel_flag_set(
    const DeformableCancelFlag *flag,
    uint8_t cancelled);
```

Sets (`cancelled` not 0) or clears (`cancelled` 0) the flag. Any thread may call it while another runs a call that reads
the flag; that call stops at its next check.

**Parameters**

- `flag` ([`const DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablecancelflag)): The flag to set or clear.
- `cancelled` (`uint8_t`): Not 0 sets the flag, 0 clears it so the flag can be used again.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.2.0/api-references/c/overview/#conventions) describe.

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

### deformable_cancel_flag_is_set

**Function** · `deformable.h`

```c
DeformableStatus deformable_cancel_flag_is_set(
    const DeformableCancelFlag *flag,
    uint8_t *cancelled);
```

Writes 1 to `cancelled` when the flag is set and 0 otherwise.

**Parameters**

- `flag` ([`const DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/errors/#deformablecancelflag)): The flag to read.
- `cancelled` (`uint8_t *`): Out. Receives 1 when the flag is set, 0 otherwise.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.2.0/api-references/c/overview/#conventions) describe.

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