Error Reference

Tribunus Compute uses a structured error taxonomy for all backend operations. Every error that escapes a Realizer implementation belongs to exactly one of the 11 types defined below. This exhaustive classification means you can handle every known failure mode without catching opaque generic errors.

The errors are grouped by the stage in which they originate: Compilation, Admission, or Runtime.

Error Table

Error	Code	Stage	Description	Suggested Fix
unsupported_dtype	RZ-0001	Compilation	Operation requested a dtype not realised by this backend. Each backend advertises its supported dtype set at compile time; requesting a dtype outside that set triggers this error.	Use --fallback-dtype to downcast, or switch to a backend that supports the requested dtype natively.
unsupported_layout	RZ-0002	Compilation	The memory layout implied by the operation graph cannot be mapped to the backend’s native layout. Tensors scheduled in a blocked or tiled layout may not be realisable on backends that expect a flat row-major scheme.	Re-compile with --layout-policy=relaxed to allow the compiler to transpose or permute the layout automatically.
unsupported_mutation	RZ-0003	Compilation	An in-place or aliased mutation was requested on a tensor that the backend lane cannot modify without breaking data dependencies. Some backends lack atomic or scoped-mutation primitives for certain memory regions.	Disable in-place optimisations for this backend with --no-inplace-ops, or isolate the mutated tensor into its own allocation.
unsupported_dynamic_shape	RZ-0004	Compilation	A dynamic shape was encountered where the compiler required a compile-time static shape. The compile-ahead architecture must freeze all tensor dimensions before kernel selection.	Provide static shapes at compile time, or enable dynamic shape mode (incurs a performance penalty via shape-generic fallback kernels).
compile_failed	RZ-0007	Compilation	The backend compiler rejected the candidate kernel during compilation. This can happen when the kernel exceeds backend resource limits, uses an unsupported intrinsic, or violates backend-specific constraints.	Check the backend compiler output log for the specific rejection reason. Adjust kernel parameters or simplify the operation.
load_failed	RZ-0008	Runtime	The compiled kernel or library failed to load into the runtime environment. Possible causes include missing driver libraries, incompatible ABI versions, or corrupt compute image artifacts.	Rebuild the compute image from source. Verify that the target machine has compatible driver versions installed.
numerical_divergence	RZ-0009	Admission	A candidate kernel exceeded the oracle tolerance threshold during the admission phase. The 4-tier numerical oracle (Exact, Approximate, Heuristic, Unverified) flagged the kernel’s output as too far from the golden reference (Apple Silicon FP32).	Tune the kernel’s precision schedule or increase the oracle tolerance via --oracle-tolerance=<level>. Verify that the golden reference itself is well-conditioned for this operation.
performance_regression	RZ-0010	Admission	The candidate kernel was slower than the reference baseline by more than the configured regression threshold. Admission compares each candidate against the best known kernel for the same operation shape and dtype.	Enable --allow-slower-candidates for development and profiling workflows, or tune the kernel to close the performance gap.
replay_invalid	RZ-0011	Runtime	The compute image’s compiled state is inconsistent with the current runtime environment. This can happen when deploying a compute image built for a different GPU architecture, driver version, or memory configuration.	Re-compile the compute image for the current runtime environment. Ensure consistent hardware and driver versions across build and deploy targets.
cache_key_mismatch	RZ-0012	Runtime	The autotune cache key computed at runtime does not match any entry in the compiled cache. This occurs when deployment parameters (device count, memory capacity, driver version) differ from those used during autotuning.	Flush the autotune cache with --flush-cache and re-compile. For stable deployments, pin the cache key components to match the build environment.
runtime_driver_fault	RZ-0013	Runtime	A driver or hardware error occurred during kernel execution. This is a catch-all for GPU crashes, device timeouts, memory access violations, and driver-level failures that the backend cannot recover from.	Check driver version compatibility and hardware status (nvidia-smi or metal GPU report). Reboot the machine if the device is in an unrecoverable state.

Diagnostics

When a RealizerError is raised, the runtime emits a structured log line containing the error type, code, originating backend, operation name, tensor shapes, and a backend-specific diagnostic payload. Use tribunus-compute logs --level=debug to inspect these diagnostics. The structured log format is JSON and can be piped into external observability tools.

Handling Errors in SDK Code

The TypeScript SDK exports typed error classes for each RealizerError code. Catch specific error types to implement granular fallback logic:

import { UnsupportedDtypeError, CompileFailedError } from '@tribunus/sdk';

try {
  await compute.compile(modelGraph, { backend: 'cuda' });
} catch (e) {
  if (e instanceof UnsupportedDtypeError) {
    // fall back to CPU-like dtype
    e.fallback({ dtype: 'fp32' });
  } else if (e instanceof CompileFailedError) {
    // log compiler output and retry with relaxed constraints
    console.error(e.compilerLog);
  }
}