Mintplex-Labs/anything-llm · error · Error

Username must start with a lowercase letter and only contain

Error message

Username must start with a lowercase letter and only contain lowercase letters, numbers, underscores, hyphens, and periods

What it means

Thrown by User.validations.username when the value fails User.usernameRegex (/^[a-z][a-z0-9._@-]*$/). It must start with a lowercase letter and may contain only lowercase letters, digits, underscores, periods, hyphens, and @ signs. Note the error message omits the @ sign that the regex and the code comment both permit — a real @ in the value is actually accepted.

Source

Thrown at server/models/user.js:43

    "dailyMessageLimit",
    "bio",
  ],
  validations: {
    /**
     * Unix-style username regex:
     * - Must start with a lowercase letter
     * - Can contain lowercase letters, digits, underscores, hyphens, @ signs, and periods
     * - 2-64 characters long
     */
    username: (newValue = "") => {
      try {
        const username = String(newValue);
        if (username.length > 64)
          throw new Error("Username cannot be longer than 64 characters");
        if (username.length < 2)
          throw new Error("Username must be at least 2 characters");
        if (!User.usernameRegex.test(username))
          throw new Error(
            "Username must start with a lowercase letter and only contain lowercase letters, numbers, underscores, hyphens, and periods"
          );
        return username;
      } catch (e) {
        throw new Error(e.message);
      }
    },
    role: (role = "default") => {
      const VALID_ROLES = ["default", "admin", "manager"];
      if (!VALID_ROLES.includes(role)) {
        throw new Error(
          `Invalid role. Allowed roles are: ${VALID_ROLES.join(", ")}`
        );
      }
      return String(role);
    },
    dailyMessageLimit: (dailyMessageLimit = null) => {
      if (dailyMessageLimit === null) return null;

View on GitHub (pinned to 526360e320)

Solutions

1. Lowercase the username and ensure it starts with a lowercase letter.
2. Strip spaces and any character outside [a-z0-9._@-].
3. In SSO mapping, normalize the external identifier to a compliant handle.

Example fix

// before
const validated = User.validations.username('John Doe');
// after
const handle = 'john.doe'.toLowerCase().replace(/[^a-z0-9._@-]/g, '');
const validated = User.validations.username(handle);

const USERNAME_RE = /^[a-z][a-z0-9._@-]*$/;
function normalizeUsername(raw) {
  return String(raw).toLowerCase().replace(/[^a-z0-9._@-]/g, '');
}

const isValidUsername = (u) => typeof u === 'string' && /^[a-z][a-z0-9._@-]*$/.test(u);

When it happens

Trigger: Creating/updating a username that starts with an uppercase letter, a digit, a symbol, or that contains uppercase letters, spaces, or disallowed symbols (e.g. 'John', '1abc', 'ab cd', 'ab!').

Common situations: SSO/IdP returns an email-style or mixed-case principal that does not satisfy the Unix-style rule. User pastes a display name with capitals. Import from a system that permits uppercase.

Related errors

• Username cannot be longer than 64 characters
• Username must be at least 2 characters
• Invalid role. Allowed roles are: ${VALID_ROLES.join(", ")}
• Daily message limit must be null or a number greater than or
• Bio cannot be longer than 1,000 characters

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