Netlify deploy fails if netlify.toml env vars are not type "string"?

Hello team,

I’m running into something I’m not sure is intended behavior.

I have local .env vars for dev in a .env file

I have those same variables declared in the netlify.toml file under [build.environment] with the appropriate variables for production.

The difference is, my local build can handle boolean and number env var types, but the netlify.toml / parsing insists that everything become a string.

In particular, I’m worried that if this is intended, I might have to convert local vars to string as well, and then cast everything to string wherever those vars are used in my codebase.

Exact error message:

2:56:04 PM: Preparing Git Reference pull/10/head
2:56:06 PM: Parsing package.json dependencies
2:56:07 PM: Creating deploy upload records
2:56:07 PM: Failing build: Failed to parse configuration
2:56:07 PM: Failed during stage 'Reading and parsing configuration files': 
  "siteInfo": {
    "id": "redacted"
  "accounts": [],
  "addons": [],
  "env": {},
  "configPath": "/opt/build/repo/netlify.toml",
  "redirectsPath": "/opt/build/repo/build/_redirects",
  "headersPath": "/opt/build/repo/build/_headers",
  "buildDir": "/opt/build/repo",
  "repositoryRoot": "/opt/build/repo",
  "config": {
    "headersOrigin": "config",
    "redirectsOrigin": "config",
    "functions": {
      "*": {}
    "plugins": [
        "package": "@sentry/netlify-build-plugin",
        "origin": "ui",
        "inputs": {}
    "build": {
      "environment": {
        "BRANCH": "dev",
        "CONTEXT": "deploy-preview",
        "DEPLOY_PRIME_URL": "redacted",
        "DEPLOY_URL": "redacted",
        "GO_VERSION": "1.14.4",
        "NETLIFY_IMAGES_CDN_DOMAIN": "redacted",
        "REVIEW_ID": "10",
        "SITE_ID": "redacted",
        "SITE_NAME": "redacted",
        "URL": "redacted",
        "MY_ENV_VAR1": 12345
        "MY_ENV_VAR1": true
      "publish": "/opt/build/repo/build",
      "publishOrigin": "config",
      "processing": {
        "css": {},
        "html": {},
        "images": {},
        "js": {}
      "services": {},
      "base": "/opt/build/repo",
      "command": "yarn build",
      "commandOrigin": "config"
    "headers": [
        "for": "/*",
        "values": {
          "X-Frame-Options": "DENY",
          "X-XSS-Protection": "1; mode=block",
          "Content-Security-Policy": "frame-ancestors",
          "cache-control": "max-age=0, no-cache, no-store, must-revalidate"
  "context": "deploy-preview",
  "branch": "dev"
: json: cannot unmarshal number into Go struct field of type string


        "MY_ENV_VAR1": 12345
        "MY_ENV_VAR2": true

Local builds, with yarn build or netlify build work fine. I can also do a netlify manual deploy via cli without an issue. This is only a problem when building from a commit or deploy preview.


(other stuff removed)
# Results in error "json: cannot unmarshal number into Go struct field of type string
        "MY_ENV_VAR1": 12345
# Results in error "json: cannot unmarshal bool into Go struct field of type string"
        "MY_ENV_VAR2": true

My questions:

  1. Is this intended behavior? Am I missing a standard for env vars that say they should all be strings?
  2. Why would the build fail when building via Netlify’s cloud deployment environment, but works locally with netlify cli build ? Shouldn’t they both process the env vars from netlify.toml via the same script/library/etc?
  3. If this is intended or if I need to do a workaround by converting number and bool values to string, will my strict checking of those values in my app (e.g. will I start having (true === “true”) fail everywhere because of this?)

Thanks Netlify team!


After some reading, it seems this is largely related to env vars typically being strings, and not really having good support / specs for anything else.

I’m seeing a lot of hacks for parsing booleans, such as switching to using 1 or JSON.parse(process.env.my_var.toLowerCase()), etc.

I’d love to get an official Netlify answer before implementing a fix in my own codebase, if necessary.

Current running list of suggestions for Netlify:
More helpful error messages / clearly identify which env var caused the issue / continue with the rest of the env vars if parse failed for one of them?
CLI parsing/validation :white_check_mark: for netlify.toml / local env vars that checks types for env vars / warns :rotating_light: if incorrect types.
Netlify documentation / examples warning about this in your support docs (like 1, 2) :slight_smile: .

Hi @danielthedifficult,

Yes, that is expected behaviour as UNIX environment variables are always returned as strings. So, we expect users to provide strings in the TOML file too.

1 Like