BoundaryML/baml · error · RuntimeError

Failed to initialize BAML runtime

Error message

Failed to initialize BAML runtime

What it means

Raised when Baml::Runtime.from_directory cannot construct the BAML runtime from the given directory containing .baml files. The underlying cause is formatted into the RuntimeError via anyhow's context, so the real validation/compiler error follows the message text.

Source

Thrown at engine/language_client_ruby/ext/ruby_ffi/src/lib.rs:61

            .build()
            .map_err(|e| {
                Error::new(
                    ruby.exception_runtime_error(),
                    format!("Failed to start tokio runtime because:\n{e:?}"),
                )
            })
    }

    pub fn from_directory(
        ruby: &Ruby,
        directory: PathBuf,
        env_vars: HashMap<String, String>,
    ) -> Result<BamlRuntimeFfi> {
        let baml_runtime =
            match BamlRuntime::from_directory(&directory, env_vars, FeatureFlags::new()) {
                Ok(br) => br,
                Err(e) => {
                    return Err(Error::new(
                        ruby.exception_runtime_error(),
                        format!("{:?}", e.context("Failed to initialize BAML runtime")),
                    ))
                }
            };

        let rt = BamlRuntimeFfi {
            inner: Arc::new(baml_runtime),
            t: Arc::new(Self::make_tokio_runtime(ruby)?),
        };

        Ok(rt)
    }

    pub fn from_files(
        ruby: &Ruby,
        root_path: String,
        files: HashMap<String, String>,

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Read the {:?} output after the message — it contains the specific compiler/IO error.
2. Verify the directory is the BAML source directory (contains .baml files, e.g. baml_src/).
3. Run `baml-cli dev` or the BAML CLI on the same directory to surface syntax/config errors quickly.
4. Fix any reported .baml syntax or client configuration errors, then retry.

Example fix

// before
Baml::Runtime.from_directory('./src', ENV.to_h)   # wrong dir, no .baml files
// after
Baml::Runtime.from_directory('./baml_src', ENV.to_h) # directory with valid .baml files

dir = './baml_src'
raise ArgumentError, "#{dir} is not a directory" unless Dir.exist?(dir)
raise ArgumentError, "no .baml files in #{dir}" if Dir.glob(File.join(dir, '**/*.baml')).empty?

begin
  runtime = Baml::Runtime.from_directory(dir, ENV.to_h)
rescue RuntimeError => e
  logger.error("BAML init failed: #{e.message}")
  raise
end

When it happens

Trigger: Baml::Runtime.from_directory(directory, env_vars) is called with a directory path that doesn't exist, has no valid .baml files, or whose BAML sources fail to compile (syntax errors, invalid config, bad client definitions).

Common situations: Pointing from_directory at the wrong project root (baml_src missing); renaming or deleting .baml files; BAML syntax errors after edits; stale references to removed BAML functions/clients.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• Package initialization failed: {0}
• Configuration error: {0}
• Invalid client property. Should have been a fallback propert
• Unsupported strategy provider: {}
• Unsupported strategy provider: {}. Available ones are: {}

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