error.h File Reference

Error types for cross-.so error reporting. More...

#include <stddef.h>
#include <entropic/entropic_export.h>

Include dependency graph for error.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct entropic_engine *	entropic_handle_t
	Opaque handle to an entropic engine instance.
typedef void(*	entropic_error_callback_t) (entropic_error_t code, const char *message, void *user_data)
	Error callback type for async error reporting.

Enumerations
enum	entropic_error_t {   ENTROPIC_OK = 0 , ENTROPIC_ERROR_INVALID_ARGUMENT , ENTROPIC_ERROR_INVALID_CONFIG , ENTROPIC_ERROR_INVALID_STATE ,   ENTROPIC_ERROR_MODEL_NOT_FOUND , ENTROPIC_ERROR_LOAD_FAILED , ENTROPIC_ERROR_GENERATE_FAILED , ENTROPIC_ERROR_TOOL_NOT_FOUND ,   ENTROPIC_ERROR_PERMISSION_DENIED , ENTROPIC_ERROR_PLUGIN_VERSION_MISMATCH , ENTROPIC_ERROR_PLUGIN_LOAD_FAILED , ENTROPIC_ERROR_TIMEOUT ,   ENTROPIC_ERROR_CANCELLED , ENTROPIC_ERROR_OUT_OF_MEMORY , ENTROPIC_ERROR_IO , ENTROPIC_ERROR_INTERNAL ,   ENTROPIC_ERROR_SERVER_ALREADY_EXISTS , ENTROPIC_ERROR_SERVER_NOT_FOUND , ENTROPIC_ERROR_CONNECTION_FAILED , ENTROPIC_ERROR_INVALID_HANDLE ,   ENTROPIC_ERROR_TOOL_EXECUTION_FAILED , ENTROPIC_ERROR_STORAGE_FAILED , ENTROPIC_ERROR_IDENTITY_NOT_FOUND , ENTROPIC_ERROR_ALREADY_RUNNING ,   ENTROPIC_ERROR_NOT_RUNNING , ENTROPIC_ERROR_NOT_IMPLEMENTED , ENTROPIC_ERROR_INTERRUPTED , ENTROPIC_ERROR_ADAPTER_NOT_FOUND ,   ENTROPIC_ERROR_ADAPTER_LOAD_FAILED , ENTROPIC_ERROR_ADAPTER_SWAP_FAILED , ENTROPIC_ERROR_ADAPTER_CANCELLED , ENTROPIC_ERROR_GRAMMAR_NOT_FOUND ,   ENTROPIC_ERROR_GRAMMAR_INVALID , ENTROPIC_ERROR_MCP_KEY_DENIED , ENTROPIC_ERROR_LIMIT_REACHED , ENTROPIC_ERROR_ALREADY_EXISTS ,   ENTROPIC_ERROR_IN_USE , ENTROPIC_ERROR_PROFILE_NOT_FOUND , ENTROPIC_ERROR_TIME_LIMIT_EXCEEDED , ENTROPIC_ERROR_VALIDATION_FAILED ,   ENTROPIC_ERROR_COMPACTION_FAILED , ENTROPIC_ERROR_MODEL_NOT_ACTIVE , ENTROPIC_ERROR_EVAL_CONTEXT_FULL , ENTROPIC_ERROR_EVAL_FAILED ,   ENTROPIC_ERROR_IMAGE_LOAD_FAILED , ENTROPIC_ERROR_IMAGE_TOO_LARGE , ENTROPIC_ERROR_MMPROJ_LOAD_FAILED , ENTROPIC_ERROR_UNSUPPORTED_URL ,   ENTROPIC_ERROR_NOT_SUPPORTED , ENTROPIC_ERROR_STATE_INCOMPATIBLE , ENTROPIC_ERROR_NO_VISION_TIER , ENTROPIC_ERROR_QUEUE_FULL ,   ENTROPIC_ERROR_SPECULATIVE_INCOMPATIBLE_ARCH , ENTROPIC_ERROR_TIER_MODEL_TOO_LARGE , ENTROPIC_ERROR_SPECULATIVE_INCOMPATIBLE_CONFIG }
	Error codes returned by all C API functions. More...

Functions
ENTROPIC_EXPORT const char *	entropic_last_error (entropic_handle_t handle)
	Get the last error message for a handle.
ENTROPIC_EXPORT const char *	entropic_error_name (entropic_error_t code)
	Get the human-readable name for an error code.
ENTROPIC_EXPORT entropic_error_t	entropic_set_error_callback (entropic_handle_t handle, entropic_error_callback_t callback, void *user_data)
	NOT IMPLEMENTED — reserved.

Detailed Description

Error types for cross-.so error reporting.

Exceptions do NOT cross .so boundaries. All cross-boundary error reporting uses:

1. Return codes — C API functions return entropic_error_t.
2. Error callbacks — consumer registers for async errors.
3. Error state on handles — entropic_last_error() returns last message.

Thread safety

entropic_last_error() is per-handle, not global. Each handle maintains its own error state. Thread-safe for different handles; concurrent access to the SAME handle requires external synchronization.

Version

1.8.0

Definition in file error.h.

Typedef Documentation

entropic_error_callback_t

typedef void(* entropic_error_callback_t) (entropic_error_t code, const char *message, void *user_data)

Error callback type for async error reporting.

Registered via entropic_set_error_callback(). Called from the thread where the error occurs. The callback MUST NOT call back into the entropic API (deadlock risk). Keep callbacks short — log and return.

Parameters

code	Error code.
message	Null-terminated error message. Valid only for callback duration.
user_data	Opaque pointer passed during registration. @callback

Version

1.8.0

Definition at line 149 of file error.h.

entropic_handle_t

typedef struct entropic_engine* entropic_handle_t

Opaque handle to an entropic engine instance.

All per-handle functions (including entropic_last_error) operate on this. Created by entropic_create(), destroyed by entropic_destroy().

Definition at line 101 of file error.h.

Enumeration Type Documentation

entropic_error_t

enum entropic_error_t

Error codes returned by all C API functions.

ENTROPIC_OK (0) on success. All other values indicate failure. Use entropic_error_name() to get a human-readable string for logging.

@req REQ-TYPE-002

Enumerator
ENTROPIC_OK	Success.
ENTROPIC_ERROR_INVALID_ARGUMENT	NULL pointer, empty string, out-of-range value.
ENTROPIC_ERROR_INVALID_CONFIG	Config validation failed (missing fields, bad values)
ENTROPIC_ERROR_INVALID_STATE	Operation not valid in current state (e.g., generate before activate)
ENTROPIC_ERROR_MODEL_NOT_FOUND	Model file does not exist at resolved path.
ENTROPIC_ERROR_LOAD_FAILED	Model load failed (corrupt file, OOM, unsupported format)
ENTROPIC_ERROR_GENERATE_FAILED	Generation failed (context overflow, model error)
ENTROPIC_ERROR_TOOL_NOT_FOUND	Requested tool not registered.
ENTROPIC_ERROR_PERMISSION_DENIED	Tool call blocked by permission manager.
ENTROPIC_ERROR_PLUGIN_VERSION_MISMATCH	Plugin API version != engine expected version.
ENTROPIC_ERROR_PLUGIN_LOAD_FAILED	dlopen/dlsym failed on plugin .so
ENTROPIC_ERROR_TIMEOUT	Operation exceeded time limit.
ENTROPIC_ERROR_CANCELLED	Operation cancelled via cancel token.
ENTROPIC_ERROR_OUT_OF_MEMORY	Allocation failed (system RAM or VRAM)
ENTROPIC_ERROR_IO	File/network I/O error.
ENTROPIC_ERROR_INTERNAL	Unexpected internal error (bug)
ENTROPIC_ERROR_SERVER_ALREADY_EXISTS	MCP server name already registered (v1.8.7)
ENTROPIC_ERROR_SERVER_NOT_FOUND	MCP server name not found (v1.8.7)
ENTROPIC_ERROR_CONNECTION_FAILED	Transport connection failed (v1.8.7)
ENTROPIC_ERROR_INVALID_HANDLE	NULL or destroyed handle (v1.8.9)
ENTROPIC_ERROR_TOOL_EXECUTION_FAILED	Tool call returned error (v1.8.9)
ENTROPIC_ERROR_STORAGE_FAILED	Storage operation failed (v1.8.9)
ENTROPIC_ERROR_IDENTITY_NOT_FOUND	Identity name not in config (v1.8.9)
ENTROPIC_ERROR_ALREADY_RUNNING	entropic_run already in progress on handle (v1.8.9)
ENTROPIC_ERROR_NOT_RUNNING	Interrupt called but nothing running (v1.8.9)
ENTROPIC_ERROR_NOT_IMPLEMENTED	Feature stub, not yet available (v1.8.9)
ENTROPIC_ERROR_INTERRUPTED	Operation interrupted via entropic_interrupt (v1.8.9)
ENTROPIC_ERROR_ADAPTER_NOT_FOUND	Adapter name not recognized (v1.9.2)
ENTROPIC_ERROR_ADAPTER_LOAD_FAILED	LoRA file invalid or incompatible with base model (v1.9.2)
ENTROPIC_ERROR_ADAPTER_SWAP_FAILED	Swap failed (e.g., base model not ACTIVE) (v1.9.2)
ENTROPIC_ERROR_ADAPTER_CANCELLED	ON_ADAPTER_SWAP hook cancelled the operation (v1.9.2)
ENTROPIC_ERROR_GRAMMAR_NOT_FOUND	Grammar key not in registry (v1.9.3)
ENTROPIC_ERROR_GRAMMAR_INVALID	GBNF parse failed (v1.9.3)
ENTROPIC_ERROR_MCP_KEY_DENIED	Tool call denied by MCP key set (v1.9.4)
ENTROPIC_ERROR_LIMIT_REACHED	Resource limit exceeded (e.g., max_identities) (v1.9.6)
ENTROPIC_ERROR_ALREADY_EXISTS	Named resource already exists (v1.9.6)
ENTROPIC_ERROR_IN_USE	Resource is currently active and cannot be removed (v1.9.6)
ENTROPIC_ERROR_PROFILE_NOT_FOUND	Profile name not in registry (v1.9.7)
ENTROPIC_ERROR_TIME_LIMIT_EXCEEDED	Generation terminated by time cap (v1.9.7)
ENTROPIC_ERROR_VALIDATION_FAILED	Critique generation failed — infrastructure, not content (v1.9.8)
ENTROPIC_ERROR_COMPACTION_FAILED	Custom compactor returned non-zero and default fallback also failed (v1.9.9)
ENTROPIC_ERROR_MODEL_NOT_ACTIVE	Model exists but not in ACTIVE state (v1.9.10)
ENTROPIC_ERROR_EVAL_CONTEXT_FULL	Sequence exceeds model context window (v1.9.10)
ENTROPIC_ERROR_EVAL_FAILED	Evaluation failed (llama_decode error) (v1.9.10)
ENTROPIC_ERROR_IMAGE_LOAD_FAILED	Image file could not be read or decoded (v1.9.11)
ENTROPIC_ERROR_IMAGE_TOO_LARGE	Image exceeds max_file_size (v1.9.11)
ENTROPIC_ERROR_MMPROJ_LOAD_FAILED	mmproj GGUF failed to load (v1.9.11)
ENTROPIC_ERROR_UNSUPPORTED_URL	Remote URL not supported — local file or data URI only (v1.9.11)
ENTROPIC_ERROR_NOT_SUPPORTED	Capability not supported by this backend (v1.9.13)
ENTROPIC_ERROR_STATE_INCOMPATIBLE	State buffer incompatible with current model (v1.9.13)
ENTROPIC_ERROR_NO_VISION_TIER	Image content present but no vision-capable tier (v2.1.8, gh#41)
ENTROPIC_ERROR_QUEUE_FULL	Mid-gen user-message queue at capacity (v2.1.10, gh#40)
ENTROPIC_ERROR_SPECULATIVE_INCOMPATIBLE_ARCH	Target/draft architecture is recurrent or hybrid; speculative refused (v2.1.11, gh#36)
ENTROPIC_ERROR_TIER_MODEL_TOO_LARGE	A single tier's model weights+KV exceed the engine's VRAM budget; eviction cannot help (v2.2.4, gh#57)
ENTROPIC_ERROR_SPECULATIVE_INCOMPATIBLE_CONFIG	MTP/speculative enabled but the request can't run correctly (temp>0, grammar, tools, or streaming) — fix the config or disable speculative (v2.9.1, gh#108)

Definition at line 37 of file error.h.

Function Documentation

entropic_error_name()

ENTROPIC_EXPORT const char * entropic_error_name

(

entropic_error_t

code

)

Get the human-readable name for an error code.

Parameters

code	Error code.

Returns

Static string like "ENTROPIC_ERROR_LOAD_FAILED". Never NULL.

Example

entropic_error_t err = entropic_configure(h, cfg);
if (err != ENTROPIC_OK) {
    spdlog::error("configure failed: {} — {}",
        entropic_error_name(err), entropic_last_error(h));
}

@req REQ-TYPE-003

Version

1.8.0

Parameters

code	Error code to look up.

Returns

Static string naming the error code. Never NULL. @req REQ-TYPE-003

Version

1.8.0

Definition at line 85 of file error.cpp.

entropic_last_error()

ENTROPIC_EXPORT const char * entropic_last_error

(

entropic_handle_t

handle

)

Get the last error message for a handle.

Returns the error message from the most recent failed operation on this handle. The returned string is owned by the handle and valid until the next API call on the same handle.

Parameters

handle

Engine handle (may be NULL for global errors during create).

Returns

Null-terminated error message string, or "" if no error. Owned by the handle — do NOT free.

Version

1.8.0

Get the last error message for a handle.

Pre-v2.2.6 the public symbol lived in src/types/error.cpp and ignored its handle parameter (v1.8.0 TODO never done). Moved here because the private engine_handle struct is only visible in the facade. Returns a thread-local cache copy so the pointer stays valid until the same thread reads again — matches the v1.8.0 contract documented in include/entropic/types/error.h.

Returns

Thread-local copy of this handle's last error message; the empty string when there is none. Never NULL, never freed by the caller. @req REQ-API-007 @req REQ-API-003 @req REQ-ABI-001

Version

2.2.6

Definition at line 155 of file entropic.cpp.

entropic_set_error_callback()

ENTROPIC_EXPORT entropic_error_t entropic_set_error_callback	(	entropic_handle_t	handle,
		entropic_error_callback_t	callback,
		void *	user_data
	)

NOT IMPLEMENTED — reserved.

Returns ENTROPIC_ERROR_NOT_IMPLEMENTED.

Warning

This is a stub. The callback and user_data are discarded and entropic_error_callback_t is invoked from nowhere in the engine. It is declared here because the symbol is exported and reaches the generated Python wrapper; removing it would be an ABI break.

Through v2.10.4 this returned ENTROPIC_OK, so a consumer registering a callback got success and then silence — the engine claiming a capability it does not have. As of v2.11.0 it reports ENTROPIC_ERROR_NOT_IMPLEMENTED so the absence is visible at the call site instead of at 3am.

Retrieve errors with entropic_last_error() until this is implemented.

Parameters

handle	Engine handle.
callback	Ignored.
user_data	Ignored.

Returns

ENTROPIC_ERROR_INVALID_ARGUMENT if handle is NULL, otherwise ENTROPIC_ERROR_NOT_IMPLEMENTED.

Version

2.11.0

NOT IMPLEMENTED — reserved.

Parameters

handle	Engine handle.
callback	Callback function, or NULL to remove.
user_data	Opaque pointer forwarded to callback.

Returns

ENTROPIC_OK on success, ENTROPIC_ERROR_INVALID_ARGUMENT if handle is NULL.

Version

2.11.0 @dg_internal

Definition at line 99 of file error.cpp.