Skip Ribbon Commands
Skip to main content

Quick Launch

Todd Klindt's home page > Todd Klindt's Office 365 Admin Blog > Posts > A few notes about STSADM –o migrateuser
July 29
A few notes about STSADM –o migrateuser

As those of you that have seen me present know, I do a lot with STSADM. I find it to be an incredibly useful tool for large deployments, and pretty handy for smaller ones too. I've seen a few questions on how the migrateuser operation works, so I thought I'd write a little something up. Its purpose is to move permissions from one account to another. One scenario would be if a domain was being split up. You would want the new accounts to have the same permission as the old accounts. Another use would be accountname changes. If someone's account is renamed you don't want to have to grant them permission to all of the same resources. The usage for migrateuser is pretty simple. Let's take a look:

You just supply it with the old account and the new account and that's it. If you're not migrating from one domain to another you can tell it to ignore SID history as well. Some of migrateuser's behavior isn't obvious, so I thought I'd spell some of it out. Here is a crude flowchart (I didn't do well in art in grade school) that shows the logic migrateuser uses:


Ugly, I know. The main thing I want you to take away from this is that if domain\newuser has any permissions before you run migrateuser, they will be gone and replaced with the permissions domain\olduser had. They will not be combined. To demonstrate how this works I've created a site collection and given domain\newuser and domain\olduser permissions. Domain\newuser is in the Owners group while domain\olduser is simply in the Vistors group. You can see the information in SQL in this "before" picture:

Here are the two entries for domain\newuser and domain\olduser in the UserInfo table. You can see they each have their own tp_ID and their tp_Tokens are different. This token is where their permissions are stored. In the before picture they are different. I ran this command to migrate from domain\olduser to domain\newuser:

Pretty simple, nothing too it. STSADM is finished in a flash. Now let's refresh SQL and see what changes have been made:

There are a couple of things to note here. First, note tp_ID 9 has a tp_Login value of domain\newuser instead of domain\olduser in the previous screenshot. Essentially migrateuser just changed the value. Next you'll notice the tp_Token is the same as it was before. It was not changed to domain\newuser's nor were the two combined. Finally you'll see that domain\newuser's previous tp_ID, 8, is now marked as Deleted. That's the first step in the flowchart.

Besides removing all of domain\newuser's permissions, migrateuser has another "gotcha." Since it deletes domain\newuser's permissions before it maps them to domain\olduser's permissions (even if there are no domain\olduser permissions to map) there is a split second where it's possible that no one has permission. This is the case with Site Owners. If domain\newuser is the only Site Owner (meaning a secondary wasn't defined) then after migrateuser deletes it, the Site now has no Owner and cannot be administrated. I have not seen a way to recover from that. The site still renders, and users can still use it, but no administrative tasks can be done. In both cases that I've seen this I've had to recover the site from a backup. There may be a way to fix this in SQL, but I would recommendation against editing SQL by hand.

I hope this helps you understand the migrateuser operation a little better.



How about migrating groups?

Do you know if its possible to migrate a security group? I have a customer who changed some OU in their AD. This is a problem as they use these groups for filtering content.
 on 7/29/2008 7:30 AM

Re: How about migrating groups?

I have not tried to migrate a group, I'm not sure if it's possible or not.

Todd KlindtNo presence information on 7/31/2008 10:19 PM

Re: How about migrating groups?

Ok, anyway great post! :-)
 on 8/1/2008 7:35 AM

Cannot add user because user already exists error

Hi Todd,

This is Gary.  Good post.  Another place where this works well is when the active directory account has changed, and a person gets the "Cannot add user because user already exists error", but the user isn't listed on the site.  Running this tool, with the exact same value for the -olduser and -newuser refreshes the site collection, and the user can be added.  And the old permissions are not retained.  There must be another piece of logic in there that checks to see if the old and new is the same, before deciding to delete the new.
 on 8/12/2008 7:08 AM

Re: Cannot add user because user already exists error

Hey Gary,
Good to see you.  When you get the "cannot add user" error have you tried going to Site Settings > Site Administration > (
Under Site Collection Administrator) > View Site Collection User Information and delete the user from there?  Like we've talked about recently there is a list of users for each web, and a list of users for the site collection.  Normally when you get this error the user does not exist in one, but does exist in the other.

Todd KlindtNo presence information on 8/19/2008 9:39 AM

Cannot complete this action?

Hi Todd

We are trying to use migrateuser to update a users SIP address. Her email address changed when she married and we now need to update her record in all site collections that she has visited. When we use this command we get the error Cannot complete this action. If we try the command without the -ignoresidhistory switch we get: New user account does not have valid SID history. Can you shed any light? We've had this problem for a while now. Thanks
 on 8/27/2008 2:35 PM

Re: Cannot complete this action?

The migrateuser operation only adjusts permissions nothing else.  It won't fix display names or email addresses.  If you are only using WSS there is no way to do this out of the box.  In the v2/sps space you can use Keith Richie's SPUserUtil to sync SharePoint user data with Active Directory,  I don't believe that works with WSS v3.  I know the folks at Bamboo Solutions have a product that works with v3, but it costs money.  You can find more information here, 

As to the error you're getting, I assume that the user's account has never been migrated from one domain to another.  If that is the case, then it does not have any Sid History.  Did you try running the command with the -ignoresidhistory flag?  It still won't do what you're trying to do, but I would think that would keep it from throwing an error.

Todd KlindtNo presence information on 8/28/2008 7:09 AM

Re: Cannot complete this action?

We have tried the command with and without the ignoresidhistory. The error with the ignoresidhistory is included in my original post.

So my next question to you is, can we use Sharepoint Designer to update the userinfo table without directly modifying the database?
 on 8/28/2008 9:11 AM

Re: Cannot complete this action?

I don't know of any way to fix that with SharePoint Designer.  Of course I have to mention that you should never ever alter the SharePoint databases directly, but you probably already knew that.  :)

The user could change the address herself in the UI.  She'll have to do it for each Site Collection, but it's the only free option I know of.

Todd KlindtNo presence information on 8/29/2008 3:36 PM

Keep getting user does not exist or is not unique.

We are currently going through a phased migration of several domains into one Company-wide domain. We have a local WSS v3 server that the migrateuser command seems to work well on. The issue I am having is that we also have an externally hosted box that is running MOSS. On the external box, I continue to get the "user does not exist, or is not unique" error on the accounts I have tried migrating. This happens whether or not I include the -ignoresidhistory parameter. Any information you can provide is greatly appreciated.
 on 9/9/2008 10:52 AM
1 - 10Next

Add Comment

Items on this list require content approval. Your submission will not appear in public views until approved by someone with proper rights. More information on content approval.


Body *

Today's date *

Select a date from the calendar.
Please enter today's date so I know you are a real person


Want a message when I reply to your comment? Put your Twitter handle here.