Budibase/budibase · error · GroupNameUnavailableError

Group name "${name}" is unavailable

Error message

Group name "${name}" is unavailable

What it means

When saving a user group, guardNameAvailability checks db.groups.getByName(name) and throws GroupNameUnavailableError if a group with that name already exists. Group names must be unique per tenant, so saving a new group (or renaming) with a taken name is rejected. The message names the conflicting name so the user can pick another.

Source

Thrown at packages/pro/src/sdk/groups/groups.ts:210

export async function getBulk(
  ids: string[],
  opts: { enriched: false }
): Promise<UserGroup[]>
export async function getBulk(
  ids: string[],
  opts?: { enriched?: boolean }
): Promise<UserGroup[]>
export async function getBulk(
  ids: string[],
  opts: { enriched?: boolean } = { enriched: true }
): Promise<UserGroup[] | EnrichedUserGroup[]> {
  return db.groups.getBulk(ids, opts as { enriched: true })
}

async function guardNameAvailability(name: string) {
  const existingGroup = await db.groups.getByName(name)
  if (existingGroup) {
    throw new GroupNameUnavailableError(name)
  }
}

async function getCreatorsCountInGroup(group: UserGroup) {
  let usersInGroup = await db.groups.getGroupUsers(group._id!)
  if (!usersInGroup.length) {
    return 0
  }

  const globalDb = tenancy.getGlobalDB()

  const users = await globalDb.getMultiple<User>(usersInGroup.map(u => u._id))
  const creatorsInGroup = await userUtils.creatorsInList(users)

  return creatorsInGroup.filter(x => x).length
}

function isCreatorGroup(group: Pick<UserGroup, "roles">) {

View on GitHub (pinned to a81a902e9a)

Solutions

1. Check name availability first via the groups name lookup, then save with a unique name.
2. Retry with a different/qualified name (e.g. append team or environment suffix).
3. Catch GroupNameUnavailableError in the save flow and surface a friendly 'name in use' validation message.
4. If the name belongs to a deleted group that still exists in the index, clean up stale group docs/index entries.

Example fix

// before
await groups.save({ name: "Engineering", roles: {...} })
// after
const existing = await db.groups.getByName("Engineering")
if (!existing) {
  await groups.save({ name: "Engineering", roles: {...} })
} else {
  throw new ValidationError("Group name already in use")
}

const existing = await db.groups.getByName(proposedName)
if (existing) { /* reject or pick another name before save */ }

try {
  await groups.save({ name, roles })
} catch (err) {
  if (err instanceof GroupNameUnavailableError) {
    // surface 'name already in use' and suggest an alternative
  } else throw err
}

When it happens

Trigger: Calling save() for a group whose name matches an existing group's name (case-sensitive lookup via getByName), including renaming a group to a name already used by another group.

Common situations: Two admins creating similarly-named groups concurrently; API-driven group provisioning that retries after a timeout and re-submits the same name; migrating groups from another system without checking for collisions; trailing-whitespace duplicates that still collide after normalization.

Related errors

• Email already in use: '${email}'
• Replacing members is not allowed
• Error getting status
• Unable to remove doc without a valid _id and _rev.
• Unable to bulk remove documents: ${res.error}

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/fc7c256d659e7b27. Report an issue: GitHub.