Mintplex-Labs/anything-llm · error · Error

Key must contain only letters, numbers and underscores

Error message

Key must contain only letters, numbers and underscores

What it means

Thrown by SystemPromptVariables._checkVariableKey when a variable key fails the regex /^[a-zA-Z0-9_]+$/. Keys are used as template placeholders in system prompts, so they must be valid identifiers. The check runs on both create (line 180) and update (line 204) paths, reached via the admin-only POST/PUT /system/prompt-variables endpoints.

Source

Thrown at server/models/systemPromptVariables.js:360

      }
      return result;
    } catch (error) {
      console.error("Error in expandSystemPromptVariables:", error);
      return str;
    }
  },

  /**
   * Internal function to check if a variable key is valid
   * @param {string} key
   * @param {boolean} checkExisting
   * @returns {Promise<boolean>}
   */
  _checkVariableKey: async function (key = null, checkExisting = true) {
    if (!key) throw new Error("Key is required");
    if (typeof key !== "string") throw new Error("Key must be a string");
    if (!/^[a-zA-Z0-9_]+$/.test(key))
      throw new Error("Key must contain only letters, numbers and underscores");
    if (key.length > 255)
      throw new Error("Key must be less than 255 characters");
    if (key.length < 3) throw new Error("Key must be at least 3 characters");
    if (key.startsWith("user."))
      throw new Error("Key cannot start with 'user.'");
    if (key.startsWith("system."))
      throw new Error("Key cannot start with 'system.'");
    if (checkExisting && (await this.get(key)) !== null)
      throw new Error("System prompt variable with this key already exists");

    return true;
  },
};

module.exports = { SystemPromptVariables };

View on GitHub (pinned to 526360e320)

Solutions

1. Replace every non-alphanumeric character in the key with an underscore (e.g. 'my-var' -> 'my_var').
2. Validate the key client-side with /^[a-zA-Z0-9_]+$/ before submitting to the API.
3. If you need word separators, use camelCase or snake_case only.

Example fix

// before
SystemPromptVariables.create({ key: 'my-var', value: '...' });
// after
SystemPromptVariables.create({ key: 'my_var', value: '...' });

function isValidVariableKey(key) {
  return typeof key === 'string'
    && /^[a-zA-Z0-9_]+$/.test(key)
    && key.length >= 3 && key.length <= 255
    && !key.startsWith('user.') && !key.startsWith('system.');
}

function isVariableKey(v) {
  return typeof v === 'string' && /^[a-zA-Z0-9_]+$/.test(v);
}

try {
  await SystemPromptVariables.create({ key, value });
} catch (e) {
  if (/letters, numbers and underscores/.test(e.message)) {
    // surface a field-level error to the user
  }
}

When it happens

Trigger: POST /system/prompt-variables or PUT /system/prompt-variables/:id with a key containing spaces, hyphens, dots, or any non-[A-Za-z0-9_] character (e.g. 'my-var', 'user name', 'key.1', 'café'). Any value passed through that fails the single-line character class test.

Common situations: Admins authoring a prompt variable naturally type hyphenated or human-readable names. Importing/migrating variables from external configs that permit dashes. Frontend form that submits before sanitizing the key field.

Related errors

• Key is required
• Key must be less than 255 characters
• Key cannot start with 'user.'
• Key cannot start with 'system.'
• System prompt variable with this key already exists

AI-assisted analysis of Mintplex-Labs/anything-llm@526360e320 (2026-08-13). Data as JSON: /api/errors/b5f0064ac438d2c5. Report an issue: GitHub.