Mintplex-Labs/anything-llm · warning

Key must contain only letters, numbers and underscores

Error message

Key must contain only letters, numbers and underscores

What it means

Validation rule in SystemPromptVariables._checkVariableKey: the proposed variable key failed the ^[a-zA-Z0-9_]+$ regex, meaning it contained characters other than letters, digits, or underscores — such as spaces, dashes, or punctuation — which cannot be used as a substitution key.

Solutions

1. Convert separators to underscores: my-key -> my_var becomes my_var
2. Strip or replace disallowed characters before submitting
3. Enforce the same pattern in front-end validation so users get immediate feedback

Example fix

// before
SystemPromptVariables.create({ key: 'company-name', value: 'Acme' }); // throws

// after
SystemPromptVariables.create({ key: 'company_name', value: 'Acme' });

const KEY_RE = /^[a-zA-Z0-9_]+$/;

function isValidKeyFormat(key) {
  return typeof key === 'string' && KEY_RE.test(key);
}

if (!isValidKeyFormat(key)) {
  return res.status(400).json({ error: 'Key may only contain letters, numbers, and underscores' });
}

const isPlainIdentifier = (v) => typeof v === 'string' && /^[a-zA-Z0-9_]+$/.test(v);

try {
  await SystemPromptVariables.create({ key, value });
} catch (err) {
  if (/letters, numbers and underscores/.test(err.message)) {
    return res.status(400).json({ error: 'Use snake_case for keys' });
  }
  throw err;
}

When it happens

Trigger: Using kebab-case ('my-var') instead of snake_case ('my_var'); keys containing spaces or dots ('company.name'); localized or accented characters ('cafe_zeit'); copy-pasted keys with invisible whitespace.

Common situations: Developers habitually using URL-style slugs as identifiers; keys derived from natural-language labels; keys imported from systems that permit richer alphabets.

Related errors

• Key cannot start with 'system.'
• Key cannot start with 'user.'
• Key is required
• Key must be a string
• Key must be at least 3 characters

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

Appendix: 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 3aec848f28)