What causes "Failed to register NULL constant: {}" in databendlabs/databend?

Retry in a normal environment with adequate memory

Failed to register NULL constant

Error message

Failed to register NULL constant: {}

What it means

Raised in setup_lua_environment when setting the built-in NULL constant into the metactl Lua table fails. Registration of this sentinel value is part of initializing the metactl scripting environment; failure means the Lua runtime rejected the assignment and script environment setup is aborted.

Solutions

Retry in a normal environment with adequate memory
Rebuild metactl with a consistent mlua version and feature flags
Upgrade to a release fixing the mlua set() failure
Confirm the Lua state was freshly created by setup_lua_environment and not pre-modified

Defensive patterns

Strategy: try-catch

Try / catch

match run_lua_script(&script) {
    Err(e) if e.to_string().contains("Failed to register NULL constant") => {
        eprintln!("Lua NULL export failed: {e}; verify mlua build and retry");
    }
    other => other?,
}

Prevention

Smoke-test Lua scripting (including NULL availability) after deployments
Keep mlua versions and features consistent in the build
Avoid pre-modifying the Lua state before setup_lua_environment
Run scripted commands with adequate memory limits

When it happens

Trigger: Assignment of the NULL constant to the metactl table failing — corrupted Lua state, mlua version/feature mismatch, or memory pressure.

Common situations: Same init-failure family as the other metactl table registrations; typically seen in constrained or misbuilt environments running Lua-scripted metactl commands.

Related errors

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/6a2662a259fdeda1. Report an issue: GitHub.

Appendix: source

Thrown at src/meta/control/src/lua_support.rs:425

        .set("new_grpc_client", new_grpc_client)
        .map_err(|e| anyhow::anyhow!("Failed to register new_grpc_client: {}", e))?;

    // Register new_admin_client function
    let new_admin_client = lua
        .create_function(|_lua, address: String| {
            let client = MetaAdminClient::new(&address);
            Ok(LuaAdminClient::new(client))
        })
        .map_err(|e| anyhow::anyhow!("Failed to create new_admin_client function: {}", e))?;

    metactl_table
        .set("new_admin_client", new_admin_client)
        .map_err(|e| anyhow::anyhow!("Failed to register new_admin_client: {}", e))?;

    // Export NULL constant to metactl namespace
    metactl_table
        .set("NULL", Value::NULL)
        .map_err(|e| anyhow::anyhow!("Failed to register NULL constant: {}", e))?;

    // Register spawn function that delegates to tokio::task::spawn_local
    let spawn_fn = lua
        .create_function(|_lua, func: mlua::Function| {
            #[allow(clippy::disallowed_methods)]
            let handle = tokio::task::spawn_local(async move {
                match func.call_async::<mlua::Value>(()).await {
                    Ok(result) => result,
                    Err(e) => {
                        eprintln!("Spawned task error: {}", e);
                        mlua::Value::Nil
                    }
                }
            });

            Ok(LuaTask {
                handle: Rc::new(RefCell::new(Some(handle))),
            })

View on GitHub (pinned to 288d84d76e)