{"record":{"id":"6f1358f0b4dae59f","repo":"RocketChat/Rocket.Chat","slug":"error-not-authorized-federation","errorCode":"error-not-authorized-federation","errorMessage":"Not authorized to access federation","messagePattern":"Not authorized to access federation","errorType":"error_code","errorClass":"MeteorError","httpStatus":null,"severity":"error","filePath":"apps/meteor/ee/server/hooks/federation/index.ts","lineNumber":145,"sourceCode":"\t\tif (subscription) {\n\t\t\tif (!isBannedSubscription(subscription)) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t// For federated rooms, unban requires a Matrix kick (leave) followed by a new invite.\n\t\t\t// Remove the subscription so the unban propagates to Matrix via the afterUnbanFromRoom callback,\n\t\t\t// then let the flow continue to create a new INVITED subscription via the beforeAddUserToRoom hook.\n\t\t\tawait Subscriptions.removeById(subscription._id);\n\n\t\t\tawait Message.saveSystemMessage('user-unbanned', room._id, user.username, inviter);\n\n\t\t\tvoid notifyOnSubscriptionChanged(subscription, 'removed');\n\t\t\tvoid notifyOnRoomChangedById(room._id);\n\n\t\t\tawait afterUnbanFromRoomCallback.run({ unbannedUser: user, userWhoUnbanned: inviter }, room);\n\t\t}\n\n\t\tif (!isUserNativeFederated(user) && !(await FederationMatrix.canUserAccessFederation(user))) {\n\t\t\tthrow new MeteorError('error-not-authorized-federation', 'Not authorized to access federation');\n\t\t}\n\n\t\t// If inviter is federated, the invite came from an external transaction.\n\t\t// Don't propagate back to Matrix (it was already processed at origin server).\n\t\tif (isUserNativeFederated(inviter)) {\n\t\t\treturn;\n\t\t}\n\n\t\tawait FederationMatrix.inviteUsersToRoom(room, [user.username], inviter);\n\n\t\t// after invite is sent we create the invite subscriptions\n\t\t// TODO this may be not needed if we receive the emit for the invite event from matrix\n\t\tawait Room.createUserSubscription({\n\t\t\tts: new Date(),\n\t\t\troom,\n\t\t\tuserToBeAdded: user,\n\t\t\tinviter,\n\t\t\tstatus: 'INVITED',","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/ee/server/hooks/federation/index.ts#L127-L163","documentation":"Thrown from beforeAddUserToRoom when the invitee is not natively federated and FederationMatrix.canUserAccessFederation(user) returns false. That check fails when the user lacks the 'access-federation' permission, or — when the server validates user domains — when the user has no verified email address on the workspace's own domain. It guards both local invites into federated rooms and incoming federation traffic.","triggerScenarios":"Inviting a local user without the access-federation role into a federated room; having 'Federation (or validateUserDomain) restrict access by verified domain email' enabled while the invitee's email is unverified or on another domain; permission role changes that removed access-federation after the room was created.","commonSituations":"New users invited to a federated channel before their email was verified; admin removed access-federation from the default user roles; SSO provisioned emails on a secondary domain.","solutions":["Grant the invitee the 'access-federation' permission (role assignment in Administration > Permissions)","Have the user verify an email address on the workspace's federation domain, then retry the invite","If the domain restriction is unintended, disable the user-domain validation setting for federation"],"exampleFix":"// before: inviting and only discovering the failure from the throw\nawait addUserToRoom(room._id, user, inviter);\n\n// after: pre-check the exact gate the hook applies\nimport { FederationMatrix } from '@rocket.chat/core-services';\nimport { isUserNativeFederated } from '@rocket.chat/core-typings';\nif (!isUserNativeFederated(user) && !(await FederationMatrix.canUserAccessFederation(user))) {\n  // fix permissions / verified email first\n  throw new Error('User cannot access federation: ' + user.username);\n}\nawait addUserToRoom(room._id, user, inviter);","handlingStrategy":"validation","validationCode":"import { FederationMatrix } from '@rocket.chat/core-services';\nimport { hasPermissionAsync } from '@rocket.chat/core-services';\n\nconst mayAccessFederation = async (userId: string): Promise<boolean> => {\n  if (!(await hasPermissionAsync(userId, 'access-federation'))) return false;\n  return FederationMatrix.canUserAccessFederation({ _id: userId } as any);\n};","typeGuard":null,"tryCatchPattern":"try {\n  await addUserToRoom(rid, user, inviter);\n} catch (err: any) {\n  if (err?.error === 'error-not-authorized-federation') {\n    // grant access-federation or have the user verify a domain email, then retry\n  }\n  throw err;\n}","preventionTips":["Include access-federation in onboarding roles for users who join federated channels","Require verified domain emails before exposing federated rooms to users","Re-run permission checks after role restructuring"],"tags":["federation","permissions","authorization","email-verification"],"backgroundTag":"permission-denied","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","contentChangedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}