diff --git a/doc/update/5.4-to-6.0.md b/doc/update/5.4-to-6.0.md
index 0027d91d60aca886d08ac0edb82ca961ece3ac76..31379d81abae610e13ef95bed9c3336ca95d38e8 100644
--- a/doc/update/5.4-to-6.0.md
+++ b/doc/update/5.4-to-6.0.md
@@ -111,3 +111,21 @@ To make sure you didn't miss anything run a more thorough check with:
     sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
 
 If all items are green, then congratulations upgrade complete!
+
+### Troubleshooting
+The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following commands can be run in the rails console to look for 'bad' data.
+
+All project owners should have an owner
+```
+Project.all.select { |project| project.owner.blank? }
+```
+
+Every user should have a namespace
+```
+User.all.select { |u| u.namespace.blank? }
+```
+
+Projects in the global namespace should not conflict with projects in the owner namespace
+```
+Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? }
+```