usebruno/bruno · error · Error

Variable name: "${key}" contains invalid characters! Names m

Error message

Variable name: "${key}" contains invalid characters! Names must only contain alpha-numeric characters, "-", "_", "."

What it means

Thrown by bru.setEnvVar when the key contains characters outside the allowed set. The regex /^\w-.]*$/ at bru.js:8 permits only alphanumeric characters, underscores, hyphens, and dots. Keys with spaces, dollar signs, slashes, or other special characters are rejected at bru.js:203-207.

Source

Thrown at packages/bruno-js/src/bru.js:204

  getProcessEnv(key) {
    return this.processEnvVars[key];
  }

  hasEnvVar(key) {
    return Object.hasOwn(this.envVariables, key);
  }

  getEnvVar(key) {
    return this.interpolate(this.envVariables[key]);
  }

  setEnvVar(key, value) {
    if (!key) {
      throw new Error('Creating a env variable without specifying a name is not allowed.');
    }

    if (variableNameRegex.test(key) === false) {
      throw new Error(
        `Variable name: "${key}" contains invalid characters! Names must only contain alpha-numeric characters, "-", "_", "."`
      );
    }

    // Deep-equal compare so object/array writes that mutate in place
    // (e.g. `const c = bru.getEnvVar('cfg'); c.port = 4000; bru.setEnvVar('cfg', c);`)
    // still flip the dirty flag — strict `!==` returned false for same-reference writes.
    if (!Object.hasOwn(this.envVariables, key) || !isEqual(this.envVariables[key], value)) {
      this.envVariables[key] = value;
      this._envDirty = true;
    }
  }

  deleteEnvVar(key) {
    if (key === '__name__') return;
    if (Object.hasOwn(this.envVariables, key)) {
      delete this.envVariables[key];
      this._envDirty = true;

View on GitHub (pinned to 9bdd81c7bd)

Solutions

Rename the key to use only alphanumeric characters, underscores, hyphens, and dots (e.g., 'myVar', 'my-var', 'my.var').
Sanitize the key before calling setEnvVar: key = key.replace(/[^\w.-]/g, '_').
Avoid using request-derived strings (URLs, headers) directly as variable names.

Example fix

// before
bru.setEnvVar('Content-Type', 'application/json'); // hyphen is ok but space after colon
bru.setEnvVar('user id', 42); // space not allowed

// after
bru.setEnvVar('Content-Type', 'application/json'); // valid: hyphen allowed
bru.setEnvVar('user_id', 42); // use underscore instead of space

Defensive patterns

Strategy: validation

Validate before calling

const variableNameRegex = /^[\w-.]*$/;
function isValidVarName(key) {
  return typeof key === 'string' && key.length > 0 && variableNameRegex.test(key);
}
// before calling: if (isValidVarName(key)) bru.setEnvVar(key, value);

Try / catch

try {
  bru.setEnvVar(key, value);
} catch (e) {
  if (e.message.includes('invalid characters')) {
    const safeKey = key.replace(/[^\w.-]/g, '_');
    bru.setEnvVar(safeKey, value);
  }
}

Prevention

Use only alphanumeric characters, underscores, hyphens, and dots in variable names.
Sanitize dynamically derived keys with key.replace(/[^\w.-]/g, '_').
Avoid using request/response field names directly as variable keys without validation.

When it happens

Trigger: Calling bru.setEnvVar('my var', value) (space), bru.setEnvVar('$ref', value) (dollar sign), bru.setEnvVar('a/b', value) (slash), or bru.setEnvVar('key:val', value) (colon). Any character outside [A-Za-z0-9_-.] triggers the error.

Common situations: Using a header name or URL path segment as a variable key (may contain colons or slashes). Using template-literal interpolation that introduces spaces. Copying a variable name from a system that allows special characters.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of usebruno/bruno@9bdd81c7bd (2026-08-13). Data as JSON: /api/errors/5ea329f72c8e7cab. Report an issue: GitHub.