Netlify Environment Variable Scope for Build Functions

Answer to the Core Question

When a Netlify Function (standard or Edge) runs, it always receives the environment variables that are defined in the Site Settings → Environment variables section of the Netlify UI. These variables are injected into the AWS Lambda (or Deno runtime) at invocation time, regardless of whether the function is invoked from a production deployment, a branch deploy, or a deploy‑preview.

Confirmed Inheritance Guarantees

• All UI‑defined variables are available to the function runtime.
• Branch‑ and deploy‑context‑specific variables in the UI are respected; a preview function sees preview‑scoped vars, production sees production‑scoped vars.
• Post‑deploy hooks that trigger functions inherit the same UI variables as regular functions.
• Edge Functions (Deno) read variables via Deno.env.get(); the same UI variables are injected at runtime.

Build‑Time Variable Availability

During the build phase (the execution of your site’s build command), the build container also receives the UI‑defined environment variables. However, these are ephemeral to the build container and are not automatically carried over to the function runtime unless you explicitly re‑declare them in the UI or in netlify.toml for the function.

Variables Defined Only in netlify.toml

Variables set under [build.environment] in netlify.toml are injected into the build container, but they do not appear in the function runtime unless they are also listed in the UI. The UI is the authoritative source for runtime injection.

Practical Verification Steps

1. In the Netlify UI, create a test variable, e.g., TEST_VAR=hello, and set it for all contexts.

2. Deploy a minimal function that logs the environment:

   exports.handler = async function(event, context) {
     console.log(JSON.stringify(process.env, null, 2));
     return { statusCode: 200, body: 'ok' };
   };
   

3. Invoke the function (via the UI or netlify functions:invoke) and confirm that TEST_VAR appears in the log.

4. Check the build log for the line Environment variables to verify that the variable was injected into the build container.

What to Ask Next

To tailor the guidance to your project, could you let us know:

• Whether the function is a standard Netlify Function (Node) or an Edge Function (Deno)?
• Whether the variable in question is defined only in netlify.toml or also in the UI?

These details will determine if you need to duplicate the variable in the UI to guarantee runtime access.