BoundaryML/baml · error · HandleError

unsupported handle type

Error message

unsupported handle type

What it means

HandleError::UnsupportedHandleType is raised by the bridge_cffi handle layer when a media-access API (media_url, media_file, media_base64, media_mime_type) resolves a handle that exists in the handle table but holds something other than a media value (e.g. a function ref or engine-heap handle). resolve_media in handle.rs:62-65 matches only CffiHandleTableEntry::Adt(BexExternalAdt::Media); any other row variant hits the `_ => Err(HandleError::UnsupportedHandleType)` arm. It signals you called a media accessor on a non-media handle.

Source

Thrown at baml_language/crates/bridge_cffi/src/handle.rs:23

use bex_project::{BexExternalAdt, MediaKind, MediaValue};
use bridge_ctypes::{CffiHandleTableEntry, HANDLE_TABLE, baml_bridge::cffi::BamlHandleType};

/// An owned handle-table key and its protocol type tag.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct HandleParts {
    pub key: u64,
    pub handle_type: i32,
}

/// Failure from a safe ordinary handle or media operation.
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
pub enum HandleError {
    #[error("invalid handle")]
    InvalidHandle,
    #[error("handle type mismatch")]
    TypeMismatch,
    #[error("unsupported handle type")]
    UnsupportedHandleType,
    #[error("{0}")]
    InvalidInput(String),
}

fn insert_entry(entry: CffiHandleTableEntry) -> HandleParts {
    let handle_type = entry.handle_type() as i32;
    let key = HANDLE_TABLE.insert(entry);
    HandleParts { key, handle_type }
}

fn validate_input(value: &str, field: &str) -> Result<(), HandleError> {
    if value.contains('\0') {
        return Err(HandleError::InvalidInput(format!(
            "{field} contains an embedded NUL byte"
        )));
    }
    Ok(())
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Verify which API produced the key; only media_from_url/media_from_file/media_from_base64 (and generic media seeds) yield media-capable handles.
2. Use the matching accessor for the handle kind (e.g. function-ref APIs for function-ref handles) instead of the media_* accessors.
3. Check the handle_type tag passed in matches the row's type; re-fetch the correct handle rather than guessing the key.
4. Enable debug logging / call handle_refcount-style instrumentation to confirm the row's actual variant.

Example fix

// before
let media = media_base64(fn_ref_key, BamlHandleType::HandleMedia as i32)?; // UnsupportedHandleType
// after
let media = media_base64(media_key, BamlHandleType::HandleMedia as i32)?;

def ensure_media_handle(key, handle_type, table):
    entry = table.resolve(key)
    if entry is None:
        raise ValueError("unknown handle key")
    if entry.kind != "media":
        raise ValueError(f"handle {key} is {entry.kind}, not media")

def is_media_handle(entry) -> bool:
    return isinstance(entry, CffiHandleTableEntry) and entry.variant == "Adt" and entry.adt_kind == "Media"

try:
    url = bridge.media_url(key, handle_type)
except HandleError as e:
    if "unsupported handle type" in str(e):
        url = None  # not a media handle; route to the appropriate accessor
    else:
        raise

When it happens

Trigger: Calling media_url/media_file/media_base64/media_mime_type with a (key, handle_type) pair whose table row is a FunctionRef or BexHeapHandle entry instead of a media entry — typically a key returned by seed_function_ref_handle/seed_heap_handle or minted for a function reference.

Common situations: Mixing up keys between media handles and function-ref/heap handles in FFI code; passing a stale or reassigned key from another subsystem; test harnesses reusing seeded keys across handle kinds.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Invalid handle key: {0}
• Engine not initialized. Call create_baml_runtime first.
• Project not initialized
• invalid handle
• handle type mismatch

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/cc8402859d88bbb6. Report an issue: GitHub.