linshenkx/prompt-optimizer · error · VariableError

PREDEFINED_VARIABLE_OVERRIDE

PREDEFINED_VARIABLE_OVERRIDE

Error message

Cannot override predefined variable: ${name}

What it means

VariableManager.setVariable throws VariableError with code PREDEFINED_VARIABLE_OVERRIDE when a caller attempts to set a variable whose name matches one of the manager's predefined (built-in) variables. Predefined variables are reserved by the system and cannot be overwritten through the public API. The check is performed by isPredefinedVariable(name) before any mutation occurs.

Source

Thrown at packages/ui/src/services/VariableManager.ts:121

            return 'Name cannot start with a number.'
          case 'reservedName':
            return 'Name is reserved.'
          case 'invalidCharacters':
            return 'Name cannot contain whitespace or braces ({}).' 
          default:
            return 'Name is invalid.'
        }
      })()
      throw new VariableError(
        `Invalid variable name: ${name}. ${reasonText}`,
        name,
        undefined,
        'INVALID_VARIABLE_NAME'
      );
    }

    if (this.isPredefinedVariable(name)) {
      throw new VariableError(
        `Cannot override predefined variable: ${name}`,
        name,
        undefined,
        'PREDEFINED_VARIABLE_OVERRIDE'
      );
    }

    if (value.length > VARIABLE_VALIDATION.MAX_VALUE_LENGTH) {
      throw new VariableError(
        `Variable value too long: ${value.length} > ${VARIABLE_VALIDATION.MAX_VALUE_LENGTH}`,
        name,
        undefined,
        'VALUE_TOO_LONG'
      );
    }

    this.customVariables[name] = value;
    this.saveToStorage();

View on GitHub (pinned to 3e677b1d9f)

Solutions

1. Filter out predefined variables before calling setVariable (expose/use a listPredefinedVariables or isPredefinedVariable check)
2. Namespace user-created variables (e.g. prefix 'user.') to avoid collisions
3. If the value genuinely needs updating, use a custom variable name instead of the predefined one

Example fix

// before
variableManager.setVariable('APP_NAME', 'My App') // APP_NAME is predefined

// after
if (!variableManager.isPredefinedVariable('APP_NAME')) {
  variableManager.setVariable('APP_NAME', 'My App')
} else {
  variableManager.setVariable('user.appName', 'My App')
}

if (variableManager.isPredefinedVariable(name)) {
  // skip, rename, or warn — do not call setVariable
}

const isSafeVariableName = (vm: VariableManager, name: string): boolean =>
  !vm.isPredefinedVariable(name)

try {
  vm.setVariable(name, value)
} catch (e) {
  if (e instanceof VariableError && e.code === 'PREDEFINED_VARIABLE_OVERRIDE') return
  throw e
}

When it happens

Trigger: Calling setVariable(name, value) where name is in the predefined variable set (e.g. system-provided names registered at construction). Custom user variables are unaffected; only names colliding with predefined ones trigger this.

Common situations: User-supplied variable names forwarded directly to setVariable; migration/import tooling that re-registers all variables including built-ins; frontend forms that don't filter out predefined names from the editable list.

Related errors

• variables[${index}] is not a valid object.
• variables[${index}] is missing a valid "name" field.
• variables[${index}] is missing a valid "value" field.
• Missing variables
• VALUE_TOO_LONG

AI-assisted analysis of linshenkx/prompt-optimizer@3e677b1d9f (2026-08-27). Data as JSON: /api/errors/9b09f6e23423c14f. Report an issue: GitHub.