This is a very annoying error kind of error!

Why did this happen?

First let us be extremely clear about 3 things:

• You should always backup your site, and especially your database before attempting an upgrade.
• This kind of error does NOT happen randomly (unless your server is faulty, which is extremely rare). It happens generally because you did some bad things to your database. For example: you stopped one upgrade in the middle of its process – and that may have been months or years ago! – and then tried to start the same or a different upgrade again – possibly months or years later – without restoring a squeaky clean DB in between. You can’t do that. Upgrades must be performed entirely from start to finish or they will leave the database in a broken state.

Sometimes it appears that your DB still works after an aborted upgrade, but that is a very bad assumption. If you do not restore a clean backup after a failed upgrade, it will come back to bite you months or years later.

A note for the skeptics and the unfaithful ;)

You can skip this (and save yourself some time) if you recognize you are in this case. However, many people, when reading this, will refuse to admit that they did in fact break their DB in the past and that this heritage is now coming back to the surface. So here’s how you can prove if your DB is broken or not:

Make a fresh install of the same version of b2evolution you are currently running, but make that install in a different MySQL database which is clearly separate from the one you are trying to upgrade.

Then look at your error message. In the screenshot above it says Unknown column 'hit_ctrl' in 'evo_hitlog'. Yours will be different. There are a million possible variations of this. Sometimes a whole table will be missing or will already exist when it should not, etc.

What you need to understand from this message is that you want to have a close look at the table evo_hitlog with a tool like PhpMyAdmin. This tool is often already provided by your web host.

Compare the exact structure of the table that gives an error (evo_hitlog in this example) in the DB you are trying to upgrade with the exact structure of the same table in the fresh install of the same b2evolution version.

• If you see any difference, you should accept that you are in the case described on this page.
• If you don’t see any difference, please send us screenshots of both tables where we can clearly see they are from your 2 separate databases. Of course, also attach a screenshot of your upgrade error where the SQL error is clearly visible with some context around it. There might be a bug and we will fix it (but please note: this has happened only 1 time in 12 years so far!)

The Clean Recovery Procedure

There are a million possible variations of this error. What will change is the text in the red box in the screenshot above. It is impossible to list a solution for each. Thus, we give you a general solution below, that will put you back on track if you follow it closely. Beware: most people who have these database errors are generally people who didn’t follow the proper instructions in the past and that’s what lead them to a corrupt database. This may be your case. Please carefully consider that if you don’t follow the instructions below closely you will only make things worse.

Step 1: Make a test DB / restore a backup

If you just had a failed upgrade (or in the last couple of days), restore a backup. Seriously! If you don’t you are going to make matters worse. You have been warned.

If your failed upgrade happened way back in the past, restoring a backup that pre-dates the fail may not be an option. In that case, use your most recent backup, or make one.

You might want to restore your backup into a separate database in order to test this without touching your live site:

1. Create a new empty database, either on your server or on you local machine if you have a test environment such as MAMP / WAMP / XAMPP set up.
2. Restore your latest DB backup into that database. If you don’t have one, make one now from your live site.

However, if you’re going to work on your live site, here’s how to make sure you make a very clean restore:

1. Check that you have a backup of your database.
2. Remove all existing tables from your database
3. Check that you have really removed all tables from your database
4. Restore your DB backup

Step 2: Test the integrity of your (restored) database

If your backed up database is broken itself, trying to upgrade it is only going to break it even more. SO you should try to select the best possible working backup you have at this point.

Here’s how to test the integrity of your restored database:

1. Restore the b2evolution files that match the version of your restored database OR install that older b2evolution in a separate folder and configure it to use the database you want to test.
2. Call up the /install/index.php script for that older b2evolution version.
3. Verify that the script neither pre-selects install nor update.
   • If it preselects "install", then you are pointing to an empty database.
   • If it preselects "upgrade", your b2evolution version is not the one that matches the DB.
4. Force an "upgrade" of the old version to the same old verison even though there is theoretically nothing to upgrade… See what b2evolution tells you…

By doing this, b2evolution will actually check the database to see if it can find any minor difference with what it should be. If so, it will attempt to fix it.

Look very carefully at that output. Make a screenshot for future reference.

If you are requesting forum help, post that screenshot and specifically mention you forced an upgrade of b2evolution version X.Y on a database which already was from b2evolution version X.Y.

Step 3. Try upgrade to the latest version again

Now you have validated that you are starting with a clean database (make an additional backup, you never have enough), you can try a clean upgrade again:

1. Upload/copy the latest b2evolution release files into the folder you used for the previous test. Even if you had b2evolution version 1, you can upgrade to b2evolution v6 without doing intermediary upgrades. So upload the latest version, not an old one.
2. Call up the /install/index.php
3. Verify that the scripts preselects that you want to do an "upgrade"
4. Launch the upgrade and watch carefully what happens. Your script must not time out! If the script detects that it is a risk of timing out, it will stop and ask you to click on a "continue" link. Please do so until you reach the end of the upgrade.
5. If you have any error message, make a screenshot for future reference.

If you are requesting forum help, post the screenshot as well as the versions from b2evolution you were upgrading from and upgrading to.

Step 4. If you still have an error

Seriously, if you still have an error at this point there are 2 possible causes:

1) There is a bug in the upgrade process. This is very rare. This has happened only once in 12 years of upgrades!

2) You did NOT follow the above instructions. Most likely:

• you did NOT delete all your tables old tables
• you did NOT restore a clean backup
• you did NOT let an older b2evolution version self-check your backup

The Rocket Surgery Procedure

Now, if you want to play it McGyver style, take out your Swiss army knife and look at the screenshot above:

See the green box? This is the internal b2evolution DB version number. The upgrade process is broken down into many blocks with increasing numbers. If you restart the upgrade after an error, it will restart at the last successful checkpoint. This does NOT mean you can do this and expect it to "just work", but assuming you tweak & fix your DB as you go along, just know b2evo will restart from the latest successful checkpoint.

Every time you get to a greater number with ": OK" next to it, you’re making progress.

Now, see the red box? These are the details about the error. In case you don’t see the details, make sure you turn on debug mode .

You need to read what the details of the error are. It will likely be:

• a table doesn’t exist
• a table already exists
• a column doesn’t exist
• a column already exists
• etc. (all these are typically the result of running the upgrade once, stopping it before it finishes and then starting again from the beginning)

Now you need to fix whatever it says.

You may want to do that in conjunction with the upgrade script, and especially the contents of the file /install/_functions_evoupgrade.php.

First you would search the latest successful checkpoint. In the screenshot above, it’s 10400. So in the code you’d find:

		set_upgrade_checkpoint( '10400' );
	}


	if( $old_db_version < 10500 )
	{	//  part 3
		task_begin( 'Upgrading hitlog table...' );
		$DB->query( "ALTER TABLE T_hitlog
								CHANGE COLUMN hit_referer_type  hit_referer_type ENUM(  'search',  'special',  'spam',  'referer',  'direct',  'self',  'admin', 'blacklist' ) NOT NULL,
								ADD COLUMN hit_type ENUM('standard','rss','admin','ajax', 'service') DEFAULT 'standard' NOT NULL AFTER hit_ctrl,
								ADD COLUMN hit_action VARCHAR(30) DEFAULT NULL AFTER hit_ctrl" );
		$DB->query( 'UPDATE T_hitlog SET hit_referer_type = "special" WHERE hit_referer_type = "blacklist"' );
		$DB->query( 'UPDATE T_hitlog SET hit_type = "admin", hit_referer_type = "direct"  WHERE hit_referer_type = "admin"' );
		$DB->query( "ALTER TABLE T_hitlog
								CHANGE COLUMN hit_referer_type  hit_referer_type ENUM(  'search',  'special',  'spam',  'referer',  'direct',  'self' ) NOT NULL");
		task_end();

And there you can see the task that fails: 'Upgrading hitlog table...'

Here you can see how the script references a column named hit_ctrl.

Of course, if you had properly let b2evo repair itself at Step 2, you’d never have a problem like that.

But now, if you really want to play McGyver, you could install a brand new and fresh b2evolution into – yet another – separate database, go look what hit_ctrl is supposed to look like and then add it to your faulty database… Then, try to proceed with upgrade. Cross your fingers. It’s likely that if you have one such issue, you’ll have several more.

Desperate cases

Please seriously consider going back to steps 1, 2 and 3 in order here.

Otherwise, if you have really no other option (like your backups are corrupt) and you cannot figure out what is explained above in Step 4, please consider hiring a professional to look into your DB and do the dirty work of fixing it.