BoundaryML/baml · error · anyhow::Error

Invalid BAML_PLAYGROUND_DEV_PORT: {e}

Error message

Invalid BAML_PLAYGROUND_DEV_PORT: {e}

What it means

When BAML_PLAYGROUND_DEV_PORT is set, its value is parsed as u16 to build a dev-proxy router. If the value is not a valid unsigned integer (or outside u16), the parse error is wrapped in this anyhow message and startup aborts. The env var is present but malformed.

Source

Thrown at baml_language/crates/baml_lsp_server/src/playground_server.rs:873

    };

    let api = Router::new()
        .route("/api/ws", get(playground_ws_handler))
        .route("/api/lsp", get(lsp_ws_handler))
        .route("/api/source-files", get(source_files_handler))
        .with_state(ws_state)
        .layer(middleware::from_fn_with_state(
            access_guard,
            api_guard_middleware,
        ));

    let fallback = if let Some(dir) = playground_dir_override {
        tracing::info!("Playground: serving static files from {}", dir.display());
        static_router(dir.to_string_lossy().into_owned())
    } else if let Ok(dev_port) = std::env::var("BAML_PLAYGROUND_DEV_PORT") {
        let dev_port: u16 = dev_port
            .parse()
            .map_err(|e| anyhow::anyhow!("Invalid BAML_PLAYGROUND_DEV_PORT: {e}"))?;
        tracing::info!("Playground: dev proxy -> http://localhost:{dev_port}");
        dev_proxy_router(format!("http://localhost:{dev_port}"))
    } else if let Ok(dir) = std::env::var("BAML_PLAYGROUND_DIR") {
        tracing::info!("Playground: serving static files from {dir}");
        static_router(dir)
    } else {
        return Err(PlaygroundNotConfigured.into());
    };

    Ok(api.fallback_service(fallback))
}

fn history_project_root_for_project(project: &str) -> PathBuf {
    let fs_path = bex_project::FsPath::from_str(project.to_string());
    bex_events::history::path::resolve_project_root(fs_path.as_path())
}

// ---------------------------------------------------------------------------

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Set BAML_PLAYGROUND_DEV_PORT to a bare numeric port within 0-65535, e.g. 3000.
2. Remove surrounding quotes/whitespace from the value in your shell config.
3. Alternatively unset BAML_PLAYGROUND_DEV_PORT and set BAML_PLAYGROUND_DIR to static assets instead.
4. Verify with: echo $BAML_PLAYGROUND_DEV_PORT

Example fix

// before
export BAML_PLAYGROUND_DEV_PORT=http://localhost:3000

// after
export BAML_PLAYGROUND_DEV_PORT=3000

if let Ok(v) = std::env::var("BAML_PLAYGROUND_DEV_PORT") {
    let ok = v.trim().parse::<u16>().is_ok();
    if !ok { eprintln!("BAML_PLAYGROUND_DEV_PORT must be a port number 0-65535, got: {v}"); }
}

When it happens

Trigger: Setting BAML_PLAYGROUND_DEV_PORT to a non-numeric string (e.g. "http://localhost:3000"), a value with whitespace/quotes, a negative number, or a number above 65535; then starting the playground server without BAML_PLAYGROUND_DIR.

Common situations: Pasting a full URL instead of just the port into the env var; quoting issues in shell config leaving stray characters; typos like "3O00"; copy-pasting the whole dev server address from Vite output.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Playground server requires either BAML_PLAYGROUND_DEV_PORT o
• Configuration error: {0}
• Expected a statically defined string, not env variable
• Failed to parse client options for {}: {}
• Strategy provider is empty: {}

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