During the recent upgrade from Octopress 2 to Octopress 3, I temporarily lost all of the comments that people have left on posts. Here’s what I did to recover them.


I recently upgraded this blog from Octopress 2 to Octopress 3. The upgrade was mostly smooth, but there were a few issues to correct. The biggest was that I temporarily lost all of the comments people have left on my posts.

I use Disqus for comments, and fortunately they provide tools to help you recover from a situation like mine.

What Happened?

The root cause of almost all of the issues I ran into during the upgrade was the correction of a minor configuration issue.

On Octopress 2, I had defined the site URL as http://randycoulman.com/ (note the trailing slash). Octopress uses this URL along with the path to each post to generate the post’s ID. When it does this, it adds another / character between the site URL and the post path.

So, in Octopress 2, all of my posts had two / characters in them: http://randycoulman.com//blog/path/to/post/.

In Octopress 3, I defined the site URL correctly as http://randycoulman.com (without the trailing slash), which caused every post to get a new unique identifier.

What Broke?

While I was working on the upgrade, I discovered that I had made this change. I decided that I preferred the new IDs (without the double-/) and figured that I could deal with the resulting issues.

I knew that Octopress uses the post’s ID as the unique identifier in the Atom feed, so I just needed to allow for that to change and everything should be fine.

Unfortunately, I didn’t think of everything.

I was pretty sure that feed readers were going to think that all of the old posts were new again, so I posted a warning a few days before I launched the upgrade and apologized for the extra noise that was coming to people’s feed readers.

I also remembered that my mailing list posts are driven from the Atom feed, so I made sure to suspend those during the upgrade.

However, I forgot that I have dlvr.it watching the feed and posting to Twitter and LinkedIn whenever I publish a new article. Shortly after I launched the upgrade, a flurry of tweeted blog post links went out.

I caught that pretty quickly and tweeted an apology.

I thought that was it.

Then, a couple of days later, I received a comment on one of my older posts. That post has gotten a number of comments, but when I went to read and reply to the new comment, I discovered that all of the old comments were missing.

I checked a few other posts that I knew had comments, and they were gone as well. Oh, no! What did I do?

It turns out that Octopress uses the post’s identifier for Disqus comment threads as well.

How Do I Fix This?

I started searching Google and Disqus’ help system, and I discovered that Disqus provides a nice set of tools for dealing with issues like this.

Upgrading from Octopress 2 to Octopress 3 is pretty minor. What if I was migrating to a whole new blog engine, or moving the blog to a new domain?

It took me a while to find these tools, so I’m writing about them here in case anyone else runs into this situation and needs a solution.

Here’s what to do:

  • Go to https://disqus.com and log into your account.

  • Click on Admin in the top right corner of the navigation bar.

  • Click on Community in the top navigation bar.

  • Down the left-hand side, you’ll see a section labeled Tools.

  • Click on Migration Tools.

From there, you have three choices.

The Domain Migration Tool allows you to migrate all of your discussion threads from one domain to another, as long as there haven’t been any changes to the URL paths. This can be handy for a basic domain change, but didn’t match my situation.

The Upload a URL map option allows for a more flexible migration. If you’ve changed URL paths, domains, or protocol (say, from http to https), this option is for you. This is the direction I went; more details below.

The Redirect Crawler tool is handy if you’ve already set up 301 redirects on your old pages. Disqus will crawl those pages, follow the redirects, and update your discussion threads. Again, this didn’t match my situation.

Using the URL Mapper

Disqus provides very useful help for using the URL Mapping tool, and I recommend reading through that before getting started.

Here are the basic steps:

  • Click the Start URL mapper button.

  • Click the link labeled you can download a CSV here. This will prepare a comma-separated values (CSV) file containing all of the post IDs that Disqus has for your site. It takes a while to generate this file, so Disqus sends you an e-mail once it’s ready. Click the link to download the file and decompress it if necessary.

  • Open the file in a spreadsheet tool. For each URL in the first column, put the updated URL in the second column. In my case, if the first column contained http://randycoulman.com//blog/path/to/post/, I put http://randycoulman.com/blog/path/to/post/ in the second column.

  • Once you’ve entered all of the new paths, save the file.

  • Go back to the URL Mapper Tool.

  • Click the Choose File button and select the file you edited.

  • Click Next Step and follow any further instructions.

  • It takes a little while for the migration to complete, but once it does, you should have all of your comments back.


If you use Disqus to host comments on your site, you now have some ideas on how to recover your comments if you lose them during a migration or upgrade.

If you’ve been holding off on such a migration because you’re worried about losing the comments, this should help put your mind at ease.

I wasn’t able to find the tools on my own without searching the help system.

Once I found them, it was a bit of a tedious process but overall not that painful.

The worst part for me was that it took a few days before I realized there was even a problem.