BoundaryML/baml · error · Error

Cannot import ${name} from '@boundaryml/baml' in browser env

Error message

Cannot import ${name} from '@boundaryml/baml' in browser environment. Please import from '@boundaryml/baml/browser' instead.

What it means

The main '@boundaryml/baml' entry point only works under Node.js. When loaded in a browser (no process.versions.node), module-level shims replace Node-dependent exports such as Image with functions that throw this error, directing you to the browser-specific build.

Source

Thrown at engine/language_client_typescript/typescript_src/index.ts:12

export * from './safe_imports'

export * from './errors'

export * from './logging'

// Detect if we're in a Node.js environment
const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null

if (!isNode) {
  const browserError = (name: string) => {
    throw new Error(
      `Cannot import ${name} from '@boundaryml/baml' in browser environment. Please import from '@boundaryml/baml/browser' instead.`,
    )
  }

  // Provide helpful error messages for browser imports
  Object.defineProperty(exports, 'Image', {
    get: () => browserError('Image'),
    enumerable: true,
  })

  Object.defineProperty(exports, 'Audio', {
    get: () => browserError('Audio'),
    enumerable: true,
  });

  Object.defineProperty(exports, 'Pdf', {
    get: () => browserError('Pdf'),
    enumerable: true,

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Change imports of Node-only symbols to '@boundaryml/baml/browser'
2. Check the package's export map / bundler aliasing so browser builds pick the browser entry point
3. Keep Node-only BAML calls (Image, runtime, client) in server-side code; for SSR, guard imports to server-only modules
4. Use dynamic import inside a Node-only code path if the symbol is only needed server-side

Example fix

// before
import { Image } from '@boundaryml/baml'; // throws in browser
// after
import { Image } from '@boundaryml/baml/browser';

const isNode = typeof process !== 'undefined' && process.versions?.node;
const mod = isNode ? await import('@boundaryml/baml') : await import('@boundaryml/baml/browser');

const isNodeEnv = () => typeof process !== 'undefined' && !!process.versions?.node;

try { Image = require('@boundaryml/baml').Image; }
catch (e) { if (String(e.message).includes('browser environment')) Image = require('@boundaryml/baml/browser').Image; else throw e; }

When it happens

Trigger: Importing { Image } (or other Node-only exports) from '@boundaryml/baml' in a browser bundle (Vite/webpack/Next.js client component), or in any environment where `process.versions.node` is undefined.

Common situations: Adding BAML to a frontend app and importing from the root package; bundlers resolving the wrong export map target; SSR code accidentally executed in the browser after hydration.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Cannot import ${name} from '@boundaryml/baml' in browser env
• Missing window object
• Environment variable {key} not set
• AWS region is required to build modular request. Set it in t
• LLM client '{client_name}' requires environment variable '{k

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