BoundaryML/baml · error

failed to create media

Error message

failed to create media: %w

What it means

After encoding kwargs, newMediaFromUrl calls raw_objects.NewRawObject to create the media object in the Rust runtime. If the runtime rejects the request, the underlying error is wrapped as 'failed to create media'. This is the main failure path when constructing image/audio/pdf/video objects from a URL.

Solutions

  1. Inspect the wrapped inner error (%w chain) for the runtime's specific complaint
  2. Validate the url is non-empty and well-formed (scheme + host) before calling
  3. Ensure mimeType is a supported media type string (e.g. image/png, application/pdf) or nil for auto-detection
  4. Confirm the native BAML runtime loaded correctly and matches the Go SDK version

Example fix

// before
img, err := runtime.NewImageFromUrl("", nil) // runtime rejects empty url
// after
if u, perr := url.Parse(rawURL); perr != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid media url: %q", rawURL)
}
img, err := runtime.NewImageFromUrl(rawURL, nil)
Defensive patterns

Strategy: validation

Validate before calling

func validateUrlForMedia(rawURL string) error {
    if rawURL == "" { return errors.New("url must not be empty") }
    u, err := url.Parse(rawURL)
    if err != nil { return fmt.Errorf("unparseable url: %w", err) }
    if u.Scheme != "http" && u.Scheme != "https" { return errors.New("url must be http(s)") }
    if u.Host == "" { return errors.New("url missing host") }
    return nil
}

Try / catch

if err := validateUrlForMedia(u); err != nil { return err }
media, err := runtime.NewPDFFromUrl(u, &mime)
if err != nil {
    var inner error
    errors.As(err, &inner) // inspect wrapped runtime cause
    return fmt.Errorf("media creation rejected: %w", err)
}

Prevention

When it happens

Trigger: Calling NewImageFromUrl, NewAudioFromUrl, NewPDFFromUrl or NewVideoFromUrl with arguments the runtime rejects — e.g. an invalid/unparseable url, a mime_type string the runtime cannot accept, or a runtime-level object allocation failure.

Common situations: Passing an empty string as url, a malformed URL the runtime's parser rejects, an unsupported mime type value, or a corrupted native runtime that fails to allocate cffi objects.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at engine/language_client_go/pkg/rawobjects_constructors.go:44

	if !ok {
		return nil, fmt.Errorf("unexpected type for collector creation: %T", ptr)
	}

	return as_collector, nil
}

func (r *BamlRuntime) newMediaFromUrl(mediaType MediaType, url string, mimeType *string) (media, error) {
	kwargs, err := serde.EncodeMapEntries(map[string]any{
		"mime_type": mimeType,
		"url":       url,
	}, "media constructor args")
	if err != nil {
		return nil, fmt.Errorf("failed to encode kwargs: %w", err)
	}

	ptr, err := raw_objects.NewRawObject(r.runtime, mediaType.objectType(), kwargs)
	if err != nil {
		return nil, fmt.Errorf("failed to create media: %w", err)
	}

	as_media, ok := ptr.(media)
	if !ok {
		return nil, fmt.Errorf("unexpected type for media creation: %T", ptr)
	}

	return as_media, nil
}

func (r *BamlRuntime) NewImageFromUrl(url string, mimeType *string) (Image, error) {
	return r.newMediaFromUrl(MediaType_Image, url, mimeType)
}

func (r *BamlRuntime) NewAudioFromUrl(url string, mimeType *string) (Audio, error) {
	return r.newMediaFromUrl(MediaType_Audio, url, mimeType)
}

View on GitHub (pinned to bd85ce9dee)