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

# Errors – C API Reference – Deformable

What a failed call reports: the [`DeformableStatus`](https://help.tangerina.io/deformable/latest/api-references/c/errors/#deformablestatus) that names what went wrong, and the [`DeformableErrorDetails`](https://help.tangerina.io/deformable/latest/api-references/c/errors/#deformableerrordetails) that carries it. Then the library version, and the [`DeformableCancelFlag`](https://help.tangerina.io/deformable/latest/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/latest/api-references/c/errors/#deformable_last_error_details) writes them;
[`deformable_last_error_message`](https://help.tangerina.io/deformable/latest/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 Free's tetrahedron
count and limit, as each [`DeformableStatus`](https://help.tangerina.io/deformable/latest/api-references/c/errors/#deformablestatus) code says; they are 0 when it names none.

**Fields**

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

**See also** [Guide: Status codes and the last error](https://help.tangerina.io/deformable/latest/user-guides/c/memory-and-errors/#status-codes-and-the-last-error) · [Rust `Error`](https://help.tangerina.io/deformable/latest/api-references/rust/errors/#error) · [Python `DeformableError`](https://help.tangerina.io/deformable/latest/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/latest/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, 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.
- `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/latest/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_TETRAHEDRON_LIMIT_EXCEEDED` (`44`): Under Free, adding the object would take the scene past the 2,500 tetrahedrons one scene simulates: `first_index` is
  the tetrahedrons the scene would simulate with it (those of the objects it simulates now, and the object's),
  `second_index` the limit. Nothing is created and the rest of the scene runs. The message says both numbers, such as
  "Free: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene".
- `DEFORMABLE_STATUS_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; or
  another Deformable program on this device held the sign-in past the call's timeout.
- `DEFORMABLE_STATUS_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.
- `DEFORMABLE_STATUS_LICENSE_STORAGE_FAILED` (`47`): The per-user license store could not be written; the message names its folder.
- `DEFORMABLE_STATUS_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, the licensing service could not read the request, or its answer did not verify.

**See also** [Guide: The status codes](https://help.tangerina.io/deformable/latest/user-guides/c/memory-and-errors/#the-status-codes) · [Rust `ErrorKind`](https://help.tangerina.io/deformable/latest/api-references/rust/errors/#errorkind) · [Python `Status`](https://help.tangerina.io/deformable/latest/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/latest/user-guides/c/memory-and-errors/#status-codes-and-the-last-error) · [Rust `Error::message`](https://help.tangerina.io/deformable/latest/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/latest/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/latest/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/latest/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/latest/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/latest/api-references/c/errors/#deformable_last_error_details).

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/latest/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/latest/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/latest/api-references/rust/errors/#version) · [Python `library_version`](https://help.tangerina.io/deformable/latest/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/latest/api-references/c/errors/#deformablestatus-deformable_status_cancelled) or a running step with
[`DEFORMABLE_STEP_OUTCOME_CANCELLED`](https://help.tangerina.io/deformable/latest/api-references/c/scene/#deformablestepoutcome-deformable_step_outcome_cancelled).

[`deformable_scene_step`](https://help.tangerina.io/deformable/latest/api-references/c/scene/#deformable_scene_step), [`deformable_triangulate`](https://help.tangerina.io/deformable/latest/api-references/c/tools/#deformable_triangulate), [`deformable_tetrahedralize`](https://help.tangerina.io/deformable/latest/api-references/c/tools/#deformable_tetrahedralize) and [`deformable_autocage`](https://help.tangerina.io/deformable/latest/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/latest/user-guides/c/memory-and-errors/#cancel-a-long-call) · [Rust `CancelFlag`](https://help.tangerina.io/deformable/latest/api-references/rust/errors/#cancelflag) · [Python `CancelFlag`](https://help.tangerina.io/deformable/latest/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/latest/api-references/c/errors/#deformablecancelflag)): Out. Receives a new handle; free it with [`deformable_cancel_flag_destroy`](https://help.tangerina.io/deformable/latest/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/latest/api-references/c/overview/#conventions) describe.

**See also** [Rust `CancelFlag::new`](https://help.tangerina.io/deformable/latest/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/latest/api-references/c/errors/#deformablecancelflag)): The flag to destroy, or `NULL`.

**See also** [Python `CancelFlag.close`](https://help.tangerina.io/deformable/latest/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/latest/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/latest/api-references/c/overview/#conventions) describe.

**See also** [Rust `CancelFlag::set`](https://help.tangerina.io/deformable/latest/api-references/rust/errors/#cancelflag-set) · [Python `CancelFlag.set`](https://help.tangerina.io/deformable/latest/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/latest/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/latest/api-references/c/overview/#conventions) describe.

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