Budibase/budibase · error

Variable name has characters that are not allowed

Error message

Variable name has characters that are not allowed

What it means

Environment variable names are validated against an allowed character pattern before being written. update(varName, value, checkName) applies the value via changeValues only when the name passes validation; otherwise it throws this error without touching stored variables. It protects the variable map from keys that would break templating or storage.

Source

Thrown at packages/pro/src/sdk/environmentVariables/environmentVariables.ts:57

  if (!license.features.includes(Feature.ENVIRONMENT_VARIABLES)) {
    throw new Error(
      "User does not have access to environment variables feature."
    )
  }
  const doc = await environmentVariables.get()
  doc.variables = cb(doc.variables)
  await environmentVariables.update(doc)
}

export async function update(varName: string, value: EnvironmentVariableValue) {
  const checkName = isValid(varName)
  if (checkName) {
    await changeValues(values => {
      values[varName] = value
      return values
    })
  } else {
    throw new Error("Variable name has characters that are not allowed")
  }
}

export async function remove(varName: string) {
  await changeValues(values => {
    delete values[varName]
    return values
  })
}

export function isValid(str: string) {
  return /^[a-zA-Z0-9-_]+$/.test(str)
}

View on GitHub (pinned to a81a902e9a)

Solutions

1. Rename the variable to use only allowed characters (typically alphanumeric plus underscores).
2. Sanitize/normalize the incoming name (trim, replace invalid characters with underscores) before calling update().
3. Validate names at the API/UI boundary with the same pattern used by the SDK so users get early feedback.
4. Pass checkName=false only if you have separately guaranteed the name is valid — not as a way to bypass validation.

Example fix

// before
await environmentVariables.update("api-key-value", "secret")
// after
const safeName = "api-key-value".replace(/[^A-Za-z0-9_]/g, "_")
await environmentVariables.update(safeName, "secret")

const ALLOWED = /^[A-Za-z0-9_]+$/
if (!ALLOWED.test(varName)) {
  throw new ValidationError("Variable name may only contain letters, numbers and underscores")
}

try {
  await environmentVariables.update(varName, value)
} catch (err) {
  if (err.message.includes("characters that are not allowed")) {
    // surface validation error to user
  } else throw err
}

When it happens

Trigger: Calling update() with a varName containing characters outside the allowed set (e.g. spaces, hyphens, or other non word characters depending on the validation regex), with checkName defaulting to true.

Common situations: User-entered variable names from a form or API payload that were not sanitized; importing variable definitions from a .env file where names contain dashes; renaming conventions differing between environments.

Related errors

• Failed to generate a unique name for the row action
• Tool name must be under 64 characters long
• Column names can't contain special characters
• Error getting status
• Unable to remove doc without a valid _id and _rev.

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/96f05291dcc42e86. Report an issue: GitHub.