Mintplex-Labs/anything-llm · warning

Key cannot start with 'user.'

Error message

Key cannot start with 'user.'

What it means

Keys starting with 'user.' are reserved: the variable expansion engine maps user.* placeholders to per-user properties, so custom variables may not shadow that namespace. Note that any key containing a dot already fails the earlier character-set check, so in the current validation order this guard is defense-in-depth for the reserved namespace and rarely the first error a dotted key produces.

Solutions

1. Choose a key outside the reserved namespace, e.g. 'current_username' instead of 'user.username'
2. Rely on the built-in user.* expansion for per-user values rather than defining custom ones
3. If you need namespacing, separate with underscores which the character check permits

Example fix

// before
SystemPromptVariables.create({ key: 'user.timezone', value: 'UTC' }); // reserved prefix (and dot fails character check)

// after
SystemPromptVariables.create({ key: 'default_timezone', value: 'UTC' });

const RESERVED_PREFIXES = ['user.', 'system.'];

function usesReservedPrefix(key) {
  return typeof key === 'string' && RESERVED_PREFIXES.some((p) => key.startsWith(p));
}

if (usesReservedPrefix(key)) {
  return res.status(400).json({ error: 'Keys may not start with user. or system.' });
}

try {
  await SystemPromptVariables.create({ key, value });
} catch (err) {
  if (/cannot start with/.test(err.message)) {
    return res.status(400).json({ error: 'Reserved namespace; rename the key' });
  }
  throw err;
}

When it happens

Trigger: Attempting to create a key like 'user.name' or 'user.email' to override per-user expansion; copying a template placeholder ({{user.username}}) verbatim as a custom variable key.

Common situations: Users trying to customize per-user prompt behavior by defining their own user.* variables; importing variable sets from other prompt systems that use dotted namespaces.

Related errors

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

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

Appendix: source

Thrown at server/models/systemPromptVariables.js:365

    }
  },

  /**
   * 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)