Skip to main content

Exceptions API

veloxquant_mlx.core.exceptions

Exception hierarchy​

Exception
└── VeloxQuantError          # base for all library errors
    ├── ArtifactNotFoundError
    ├── CodebookDimensionMismatch
    ├── CyclicPipelineError
    ├── QuantizerConfigError
    └── MetalUnavailableError

VeloxQuantError​

from veloxquant_mlx.core.exceptions import VeloxQuantError

Base exception class. Catch this to handle any VeloxQuant-MLX error:

try:
    cache = KVCacheBuilder.build(model, config)
except VeloxQuantError as e:
    print(f"VeloxQuant error: {e}")

ArtifactNotFoundError​

from veloxquant_mlx.core.exceptions import ArtifactNotFoundError

Raised when a required calibration artifact (codebook, rotation, sensitivity map) is not found in the ArtifactStore.

When raised:

  • Calling VecInferKVCache without a pre-trained codebook
  • load_cached_rotations() when the path does not exist
  • NpyArtifactStore.load() for a key that was never saved
from veloxquant_mlx.core.exceptions import ArtifactNotFoundError
from veloxquant_mlx.artifacts.npy_store import NpyArtifactStore

store = NpyArtifactStore("./artifacts/")
try:
    codebook = store.load("vecinfer_codebook")
except ArtifactNotFoundError:
    print("Codebook not found. Run calibration first:")
    print("  python -m veloxquant_mlx precompute --method vecinfer --model ...")

CodebookDimensionMismatch​

from veloxquant_mlx.core.exceptions import CodebookDimensionMismatch

Raised when a loaded codebook's dimensions do not match the current model's head dimensions.

When raised:

  • Codebook was trained on a different model (different head_dim or num_subspaces)
  • Codebook was trained with a different num_subspaces than specified in KVCacheConfig

Message format: "Codebook shape [32, 8, 256, 16] incompatible with head_dim=128, num_subspaces=8"

Fix: Re-run calibration with the correct model and configuration.

CyclicPipelineError​

from veloxquant_mlx.core.exceptions import CyclicPipelineError

Raised when a CompositeQuantizer or the quantization DAG contains a cycle.

When raised:

  • Building a CompositeQuantizer where a quantizer references itself (directly or transitively)
  • Misconfigured custom pipeline using the dag.py utilities

QuantizerConfigError​

from veloxquant_mlx.core.exceptions import QuantizerConfigError

Raised when a KVCacheConfig is invalid for the requested method.

When raised:

  • method="vecinfer" without codebook or smooth_factors
  • method="spectral" without rotations
  • bits value not supported by the algorithm (e.g., bits=5 for RVQ)
  • num_subspaces does not divide head_dim evenly

Message format: "VecInfer requires 'codebook' and 'smooth_factors' in KVCacheConfig"

from veloxquant_mlx.core.exceptions import QuantizerConfigError

try:
    config = KVCacheConfig(method="vecinfer")  # missing codebook
    cache = KVCacheBuilder.build(model, config)
except QuantizerConfigError as e:
    print(e)
    # "VecInfer requires 'codebook' and 'smooth_factors' in KVCacheConfig"

MetalUnavailableError​

from veloxquant_mlx.core.exceptions import MetalUnavailableError

Raised when a Metal kernel is called on a device where Metal is not available.

When raised:

  • Calling vecinfer_quantize_metal() on an Intel Mac or in a VM
  • patch_mlx_lm_for_fused_sdpa() on an unsupported device

Fix: Run on macOS with an Apple M-series chip. See Installation troubleshooting.

See also​