{"record":{"id":"35e59541903cd573","repo":"RocketChat/Rocket.Chat","slug":"federated-user-not-found-locally","errorCode":null,"errorMessage":"Federated user not found locally","messagePattern":"Federated user not found locally","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/meteor/server/lib/rooms/createRoom.ts","lineNumber":69,"sourceCode":"\n\t\tconst { insertedId } = await Subscriptions.createWithRoomAndUser(room, owner, extra);\n\t\tawait syncRoomRolePriorityForUserAndRoom(owner._id, room._id, ['owner']);\n\n\t\tif (insertedId) {\n\t\t\tawait notifyOnSubscriptionChangedById(insertedId, 'inserted');\n\t\t\tawait notifyOnRoomChanged(room, 'inserted');\n\t\t}\n\n\t\t// Invite federated members to the room SYNCRONOUSLY,\n\t\t// since we do not use to invite lots of users at once, this is acceptable.\n\t\tconst membersToInvite = members.filter((m) => m !== owner.username);\n\n\t\tawait FederationMatrix.ensureFederatedUsersExistLocally(membersToInvite);\n\n\t\tfor (const memberUsername of membersToInvite) {\n\t\t\tconst member = await Users.findOneByUsername(memberUsername);\n\t\t\tif (!member) {\n\t\t\t\tthrow new Error('Federated user not found locally');\n\t\t\t}\n\n\t\t\tawait Room.createUserSubscription({\n\t\t\t\tts: new Date(),\n\t\t\t\troom,\n\t\t\t\tuserToBeAdded: member,\n\t\t\t\tinviter: owner,\n\t\t\t\tstatus: 'INVITED',\n\t\t\t});\n\t\t}\n\n\t\treturn;\n\t}\n\n\tconst subs = [];\n\n\tconst memberIds = [];\n","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/RocketChat/Rocket.Chat/blob/b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0/apps/meteor/server/lib/rooms/createRoom.ts#L51-L87","documentation":"While creating a federated room, Rocket.Chat first calls FederationMatrix.ensureFederatedUsersExistLocally for each invited member, then re-fetches each by username. If the federation bridge did not actually register the user locally, the subsequent Users.findOneByUsername returns null and this generic Error ('Federated user not found locally') aborts room creation.","triggerScenarios":"createRoom with extraData.federated = true and a members list containing remote usernames (user@server.tld): after ensureFederatedUsersExistLocally, Users.findOneByUsername(memberUsername) returns null for at least one member. Happens when the federation bridge silently fails to create the local ghost user or the username casing/format differs.","commonSituations":"Federation (Matrix bridge) misconfigured or the remote server unreachable while creating a federated channel; version changes in the federation app that alter ghost-user naming; inviting a user whose remote homeserver did not respond to the discovery request.","solutions":["Check federation settings and connectivity to the remote server (federation GUI/Matrix bridge logs), then retry the room creation","Inspect the users collection for the expected ghost user (username matching the remote user@domain) to see whether ensureFederatedUsersExistLocally actually persisted it","Report/patch ensureFederatedUsersExistLocally if it resolves without creating the user (silent failure in the bridge)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"await FederationMatrix.ensureFederatedUsersExistLocally(membersToInvite);\nfor (const username of membersToInvite) {\n  const exists = await Users.findOneByUsername(username, { projections: { _id: 1 } });\n  if (!exists) {\n    // back off and let the bridge retry provisioning before failing the whole creation\n    throw new Error(`Federated user ${username} not provisioned locally yet`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await createRoom(type, name, owner, members, { federated: true });\n} catch (err) {\n  if (err instanceof Error && err.message === 'Federated user not found locally') {\n    // inspect federation bridge logs, verify remote server reachability, retry with backoff\n  }\n  throw err;\n}","preventionTips":["Health-check the federation bridge before bulk federated room creation","Pre-provision ghost users and verify with Users.findOneByUsername before inviting","Alert on ensureFederatedUsersExistLocally calls that create no local user"],"tags":["federation","matrix","user-registration","room-creation"],"backgroundTag":"remote-user-provisioning-failed","analyzedSha":"b2c16d5842cbe6b69b59bdf6fc5e5f1afcd1f0b0","analyzedAt":"2026-08-18T15:26:39.429Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}