n8n-io/n8n · error · BadRequestError

Your instance is not licensed to use role "${role}".

Error message

Your instance is not licensed to use role "${role}".

What it means

Adding users to a project can assign each a project role; if a requested role is not covered by the current license, projectsService throws UnlicensedProjectRoleError (constructed as 'Your instance is not licensed to use role "<role>".'), which the addProjectUsers catch converts to a 400 BadRequestError.

Source

Thrown at packages/cli/src/controllers/project.controller.ts:327

			const relations = await this.projectsService.getProjectRelations(projectId);
			this.eventService.emit('team-project-updated', {
				userId: req.user.id,
				role: req.user.role.slug,
				members: relations.map((r) => ({ userId: r.userId, role: r.role.slug })),
				projectId,
			});

			// Response semantics:
			// - If at least one user was added, return 201. When there are also conflicts, include them in the body.
			// - If no users were added but conflicts exist, return 409 with conflicts.
			if (added.length > 0) {
				return conflicts.length > 0 ? res.status(201).json({ conflicts }) : res.status(201).send();
			}
			if (conflicts.length > 0) return res.status(409).json({ conflicts });
			return res.status(200).send();
		} catch (e) {
			if (e instanceof UnlicensedProjectRoleError) {
				throw new BadRequestError(e.message);
			}
			throw e;
		}
	}

	@Patch('/:projectId/users/:userId')
	@ProjectScope('project:update')
	async changeProjectUserRole(
		req: AuthenticatedRequest,
		res: Response,
		@Param('projectId') projectId: string,
		@Param('userId') userId: string,
		@Body body: ChangeUserRoleInProject,
	) {
		await this.assertProjectRolesNotManaged();

		try {
			await this.projectsService.changeUserRoleInProject(projectId, userId, body.role);

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Use a project role that the current license covers.
2. Upgrade the license tier to unlock the requested role.
3. Check the assignable roles for the license before issuing the add-users call.

// Validate the requested role against licensed assignable roles before POST.
async function isRoleLicensed(getAssignableRoles, role) {
  const allowed = await getAssignableRoles();
  return allowed.includes(role);
}

function isLicensedRole(role, allowedRoles) {
  return Array.isArray(allowedRoles) && allowedRoles.includes(role);
}

try {
  await api.post(`/projects/${projectId}/users`, payload);
} catch (e) {
  if (e.status === 400 && /not licensed to use role/.test(e.message)) {
    // choose a licensed role and retry
  } else { throw e; }
}

When it happens

Trigger: POST /:projectId/users with a payload role that maps to an AssignableProjectRole not enabled by the active license (e.g. an enterprise-only project role on a lower tier).

Common situations: Assigning a gated project role (limited editor / custom role) on a Community or Pro plan that does not include it; license downgraded below the role set in use.

Related errors

• Down migration only possible when there are no projects. Ple
• Cannot invite admin user without advanced permissions. Pleas
• Attempted to create a new project but quota is already exhau
• Project roles are managed automatically and cannot be change
• Bad Gateway

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/dcc134ec2aefb6c1. Report an issue: GitHub.