jUpgrade:Troubleshooting

Turning on "Debug mode"

While every effort has been made to make the migration process smooth and hassle-free, there are some situations where jUpgrade will run into errors or hang during migration with seemingly no indication of progress. For such situations it is recommended to set "Enable migration Debug" to "Yes" in the Parameters screen before running jUpgrade.

A progress log will appear below the migration steps that will update as each step is successfully completed and moved onto the next. This progress log also displays error messages and vital clues that indicate when a problem has occurred mid-step. The following is a quick guide to interpreting the log, and quick resolutions to errors with specific steps.

[checks]

Activity: jUpgrade looking for cURL, set_time_limit and writable /tmp and root folders
Success: denoted by "1"
Fixing at this stage: ensure cURL is installed and folders are writable, "disable set_time_limit" check in Parameters, or "Skip checks" altogether (not recommended)

[cleanup]

Activity: jUpgrade running cleanup script, runs when "Delete previous migration" is enabled.
Success: denoted by "1"
Fixing at this stage: ensure folder and database permissions have been granted

[download]

Activity: jUpgrade downloading Joomla distribution selected in Parameters screen
Success: denoted by "1"
Fixing at this stage: ensure folder write permissions, working internet connection; for persisting issues download distro package manually, place in /tmp folder and "Skip Download".

[decompress]

Activity: jUpgrade extracts contents of distro package into folder labelled after "Target directory"
Success: denoted by "1"
Fixing at this stage: ensure folder write permissions, valid "target directory" label, uncorrupt distro package download; for persisting issues manually extract contents into folder labelled after "target directory" and "Skip Decompress"

[install_config]

Activity: jUpgrade updates the "configuration.php" file in the folder of the newly extracted Joomla! 2.5 installation
Success: denoted by "1"
Fixing at this stage: ensure file write permissions, valid "table" and "prefix for new database" Parameter settings

[install_db]

Activity: jUpgrade creates the necessary tables for the new Joomla! 2.5 installation in the database
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove tables from previous (failed) migration and try again

[1] [users]

Activity: jUpgrade transfers registered user account information and user group mappings
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[2] [categories]

Activity: jUpgrade converts Joomla! 1.5 sections into top-level 2.5 categories and transfers all remaining 1.5 categories (retaining hierarchy) one level below
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[3] [content]

Activity: jUpgrade transfers all articles and converts "frontpage" articles into "featured" ones
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[4] [menus]

Activity: jUpgrade transfers all menus and menu items, updating the ID set to conform with 2.5's new ID numbering policy.
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[5] [modules]

Activity: jUpgrade transfers all standard modules, module parameters and menu item assignments, updating the ID set to conform with 2.5's new ID numbering
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[6] [banners]

Activity: jUpgrade transfers any banners and banner category structures that exist in the Joomla 1.5 site
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[7] [contacts]

Activity: jUpgrade transfers any contacts and contact category structures that exist in the Joomla 1.5 site
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[8] [newsfeeds]

Activity: jUpgrade transfers any newsfeeds and newsfeed category structures that exist in the Joomla 1.5 site
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[9] [weblinks]

Activity: jUpgrade transfers any weblinks and weblink category structures that exist in the Joomla 1.5 site
Success: moving onto the next step
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[files]

Activity: jUpgrade renames Joomla 2.5 images folder to "images.old" and copies over Joomla 1.5 "images" folder.
Success: moving onto the next step
Fixing at this stage: ensure folder write permissions, valid "target directory"

[10] [extensions]

Activity: jUpgrade looks for any third-party extensions that it supports and migrates the data for each one
Success: the message ";|;10;|;extensions;|;11" appears, followed by a list of extensions whose data has been migrated
Fixing at this stage: ensure database write permissions, valid "table" and "prefix for new database" Parameter settings, remove duplicate tables from previous (failed) migration and try again

[12] [ready]

Activity: jUpgrade migration complete
Success: the section for this step is displayed
Fixing at this stage: nothing to fix, migration was completed successfully.

Manually removing a failed migration

The latest version of jUpgrade (2.5.1) has a feature called "Delete previous migration" which runs a clean-up script before every migration that will remove any database tables, files or folders which were created, inserted or left over from a previous migration or failed attempt.

If for any reason this script fails while running the clean-up, you can "wipe the slate clean" and start fresh by following these instructions:

1. remove ROOT/tmp/joomla25.zip and ROOT/tmp/size.tmp
2. remove ROOT/jupgrade directory
3. delete all j17_ tables (except j16_jupgrade_categories and j16_jupgrade_menus)
4. REMOVE OLD jUpgrade installation and install the version 2.5
5. Set "Skip download" to 'No'
6. F5 to reload the browser
7. Run upgrade

Tackling specific issues

All steps appear at once and "Start jUpgrade" button does nothing when clicked

jUpgrade makes extensive use of javascript, in particular MooTools, in order to begin and proceed through the migration process. This includes the functions that operate the "Start jUpgrade" button as well as hiding the step panels and revealing them at the appropriate stage.

If the necessary javascript library is not available or has not been loaded, the button will appear with all the steps listed in a column before the migration starts.

To fix this error, make sure the MooTools 1.2 Upgrade plugin has been installed and enabled in the Plugin Manager.

"Mootools 1.2 not loaded. Please enable "System - Mootools Upgrade" plugin."

jUpgrade has been written for use with the MooTools 1.2 javascript library, and this message appears when jUpgrade detects that the MooTools 1.2 plugin that it requires to function has not been installed or is not yet enabled.

To fix this error, follow the link generated for the message to get redirected to the Plugin Manager (or access that section directly), locate the "System - Mootools Upgrade" plugin and make sure it is enabled.

To help avoid running into any MooTools javascript-related errors during the migration, also make sure that the "MooTools Upgrade" plugin is first in the order of System plugins loaded (a simple way to do this would be to assign the plugin an order number of zero "0" and saving the order list). This will ensure that this plugin runs before any other javascript plugins that might interfere and reserves the necessary variables in memory for jUpgrade's use.

The "MooTools 1.2 Upgrade" plugin comes loaded with all standard Joomla! installations since v1.5.19, so Joomla! sites of a previous version will have to be updated (the latest version of Joomla! at the time of writing is 1.5.25).

Alternatively, you can download and install the "MooTools 1.2 Upgrade" plugin separately on Joomla! installs with versions previous to 1.5.19, as that will fulfill the MooTools requirement for jUpgrade. It is highly recommended, however, to run jUpgrade after updating Joomla! to the latest version, as it has the most recent fixes and adjustments made by the Joomla! team and will maximize migration success.

"401: jupgrade_categories table not exist"

"402: jupgrade_menus table not exist"

"403: jupgrade_modules table not exist"

"404: jupgrade_steps table not exist"

When jUpgrade gets installed, one of the things it does is CREATE TABLE IF NOT EXISTS IF NOT EXISTS IF NOT EXISTSs in the Joomla! 1.5 database that help move the migration through each step. This includes tables for:

• converting sections into categories for Joomla! 2.5's category-only structure
• converting menu and menu item references to accommodate 2.5's new menu ID organization
• converting module and parameter references to accommodate 2.5's new module ID organization
• checking that a step in the migration process has been completed before moving on to the next one

If these tables have not been created, jUpgrade cannot proceed with the migration. To fix this, simply uninstall and reinstall jUpgrade, and the script that makes the tables should run and resolve the issue. (Obviously to create these tables the administrator must have the relevant permissions, but if the site is on a shared host then the server host administrator should be contacted for further assistance.)

"405: jupgrade_steps is not valid"

One of the tables crucial to jUpgrade's migration process, labelled "jupgrade_steps", stores the values for each step of the process and whether they have been completed before moving on to the next one. There are ten records stored within this database: nine of them define the sections that are migrated during the "Upgrading progress..." step, and the last concerns the migration of third party extensions.

This error message appears when the "jupgrade_steps" table has been corrupted or does not have the exact ten records which jUpgrade needs present. To fix this, simply uninstall and reinstall jUpgrade, and the script that adds the required records to the "jupgrade_steps" table should run and resolve the issue.

"406: cURL not loaded"

jUpgrade uses the cURL PHP library in order to handle the download and decompression of the new Joomla! 2.5 zip file, so having this library installed and enabled in the PHP configuration is required for jUpgrade to proceed with migration.

To fix this error, the line "extension=php_curl.dll" must be present in the php.ini file configured for the site's hosting server. Access to this file will depend on whether the site is being hosted locally and the administrator has full access, or whether the site is being hosted on a remote server, possibly shared, and the client will require the administrator's assistance to make the modification.

(Please note: in Linux environments, the line would read "extension=php_curl.so" .)

If you are running a localhost using XAMPP, 1) Open the php.ini file inside the "xampp\php" folder 2) Locate the line ;extension=php_curl.dll and remove the semi-colon 3) If the line does not exist, add it to the bottom of the php.ini file 4) Save the file and restart XAMPP (or stop and start both the Apache and MySQL services)

If your site is hosted on a remote server and you don't have access to the php.ini file, you will have to ask the server administrator to make this adjustment for you and restart the server.

You can check if cURL is installed and present by clicking on "Help >> System Info" in the main Joomla! navigation bar, then clicking on the "PHP Information" tab and scrolling down until the "cURL" section appears and displays the "cURL support" status.

There is also a manual method of testing for the php_curl module using the following instructions:

1) Create a new .php file (for e.g.: info.php) and add the following code into a text editor as the contents of the file:

<?php
// Show all information, defaults to INFO_ALL
phpinfo();
// Show just the module information.
// phpinfo(8) yields identical results.
phpinfo(INFO_MODULES);
?>

2) Upload this .php file to the root of your site (using FTP for example)
3) Now access this file using a browser (e.g.: www.yoursite.com/info.php) The page that displays will reveal whether your host supports and has enabled the cURL library.

Here are some more resources to learn about cURL and how to set it up:
http://curl.haxx.se/libcurl/php/
http://php.net/manual/en/book.curl.php
http://stackoverflow.com/questions/1347146/how-to-enable-curl-in-php

(// "CURLOPT_FOLLOWLOCATION" doesn't work with safe_mode or open_basedir)

"407: ".JPATH_ROOT." is unwritable"

"408: {$tmp} is unwritable"

Part of the migration process involves downloading the Joomla! distro selected in the Parameters screen, storing it in the /tmp folder of the Joomla! 1.5 site, extracting the contents of the distro package into a folder on the root, modifying the "configuration.php" file and copying several files and folders.

For all this to happen, the administrator requires the relevant permissions to modify the contents of their Joomla! 1.5 site folder. Otherwise jUpgrade will not have a place to store the files it needs to work with and the migration process halts.

You can check which folders are writable by clicking on "Help >> System Info" in the main Joomla! navigation bar, then clicking on the "Directory Permissions" tab to visually inspect which folders are "Writable".

To resolve this, the administrator needs to modify the permissions of the "root" and /tmp folders to allow making edits. You can use an extension such as eXtplorer to assist with this, alternatively you can set these permission using an FTP program such as FileZilla, or if on a shared host ask the server admin to assist with this. The permission level should be set to CHMOD 750 or 777.

If security is a concern on a shared hosting environment, the server admin can pre-create the jupgrade folder (or whatever label the "target directory" will have) and allow permissions to that folder alone for the purposes of the migration. In such a case, make sure "Skip Download" and "Skip Decompress" are selected and the "target directory" defined in the Parameters screen.

"409: PHP 5.2+ or greater is required"

Like all Joomla! components, jUpgrade has been written using the PHP programming language, and as such requires that PHP libraries be present to work. As time moves on and the PHP language develops, new versions are released with new functions and ways of writing code that make previous methods obsolete and eventually unusable.

Just as Joomla! 2.5 requires PHP v5.2 or greater, so to does jUpgrade. This message will appear when your version of PHP is below v5.2, and the migration will not be able to proceed because jUpgrade requires methods and functions that are not available in previous versions.

To resolve this issue, update the PHP installation on the server with the latest 5.2.x or 5.3.x release and restart the server, or if on a shared host ask the host provider for assistance. You can check the version installed by clicking on "Help >> System Info" in the main Joomla! navigation bar, then clicking on the "PHP Information" tab. The version number will be clearly displayed.

"410: MySQL 5.0+ or greater is required"

Joomla! installations work with databases to store the site information and settings, the most popular database type being MySQL. Much of the migration process in jUpgrade is handled through database queries, and these queries have been written to work with MySQL v5.0 or above.

Just as Joomla! 2.5 requires MySQL v5.0 or greater, so to does jUpgrade. This message will appear when your version of MySQL is below 5.0, and the migration will not be able to proceed because the minimum requirement has not been met.

To resolve this issue, update the MySQL installation on the server with the latest 5.x release and restart the server, or if on a shared host ask the host provider for assistance. You can check the version installed by clicking on "Help >> System Info" in the main Joomla! navigation bar, then clicking on the "PHP Information" tab. The "MySQL version" will be among the other details displayed.

"411: You must to disable 'safe_mode_gid' on your php configuration"

"412: Your destination prefix is the same of the original site"

As jUpgrade installs in the Joomla! 1.5 site , the tables it makes go into the site's database. The default prefix for 1.5 databases is "jos_", while the default prefix for 2.5 databases is "j17_" (from previous version, will be updated soon).

When jUpgrade migrates the site, the tables for both the 1.5 and 2.5 sites will be stored within the same database. jUpgrade does not allow the migration to proceed if it detects the prefix of the old database (from where it is pulling data) is the same as the prefix of the new database (where data is being transferred). If it did, you would risk breaking the migration and, more importantly, breaking the original 1.5 site database.

To resolve this issue, simply open the Parameters screen and ensure that the old and new table prefixes are different.

"Warning: set_time_limit( ) has been disabled for security reasons in..."

"Warning: set_time_limit(): Cannot set time limit due to system policy in..."

"Notice: Undefined property: stdClass::$timelimit in..."

While it can function without it, jUpgrade first opts to check for and use the value set in the server's PHP configuration for "set_time_limit". The "set_time_limit" function:

"Sets the number of seconds a script is allowed to run. If this is reached, the script returns a fatal error. The default limit is 30 seconds or, if it exists, the max_execution_time value defined in the php.ini.

When called, set_time_limit() restarts the timeout counter from zero. In other words, if the timeout is the default 30 seconds, and 25 seconds into script execution a call such as set_time_limit(20) is made, the script will run for a total of 45 seconds before timing out."
(http://php.net/manual/en/function.set-time-limit.php)

This function has legitimate purposes, however it can also potentially leave open a security hole. For this reason, most shared hosting services do not enable this function.

If any of the above messages are displayed, it is because jUpgrade is looking for the "set_time_limit" value, expecting it in order to proceed, but it is not available on the server. To resolve this, set the "Disable set_time_limit" to "Yes" in the Parameters screen so jUpgrade will ignore it as part of the initial checks.

In a desperate situation, you can remove or comment out line 43 of the "jupgrade.class.php" file in the "{root}/administrator/components/com_jupgrade/includes/" folder, which looks for the value of the server's "set_time_limit" to proceed.

"Fatal error: Uncaught exception 'JDatabaseException' with message 'Table 'j17_banners' already exists"

As part of the "Installing Joomla 2.5" step, the necessary tables are created in the the database. On a failed migration attempt, these tables need to be removed (or dropped) from the database to clear the path for a fresh install.

If you get this message, it means these tables have not been removed before jUpgrade was run. To fix this, set "Clean-up" to "Yes" in the Parameters screen and run jUpgrade. This feature should automate the clean-up and resolve the issue.

Alternatively, if that does not help, access your 1.5 site's database (such as through "phpmyadmin"), and locate and manually remove all tables that begin with the prefix that has been set as the "Prefix for new database" in the Parameters screen.

"Migrating undefined" or "[undefined][undefined]"

There may come an instance where the process will get stuck while migrating data for a specific component and (with "Debug mode" enabled) an error similar to "Migrating undefined" or "[undefined][undefined]" will be displayed.

Some causes and remedies include:

• a migrate_xxx.php file that is being requested for by jUpgrade is not available or accessible
  (these files are stored in the {root}/administrator/components/com_jupgrade/includes/ folder, labelled "migrate_xxx.php" where "xxx" is the section of content being transferred at the time.)
  To fix: uninstall and reinstall jUpgrade (to restore all required files) and try again.

• the database table from which content is being transferred is corrupt or has been modified
  (jUpgrade requires that no modifications have been made to any of the core tables themselves, otherwise the migration can run into problems when dealing with custom fields)
  To fix:download and install a maintenance component such as "Admin Tools!" and run a database integrity check and repair. Alternatively the database may have to be repaired manually using "phpmyadmin" or a similar interface. A solution for databases with custom fields is being looked into, but for the moment those must be migrated manually, or if they interfere with the migration, removed. (Of course a backup should be run before any such operation.)

• the migration runs into an issue attempting to copy content over to a database which already has content (from a previous migration, failed or not).
  To fix: remove all the tables created for the new Joomla! install during the migration and run jUpgrade again.

• the Javascript which handles the migration process has run into a problem
  To fix:check in the Plugin Manager to ensure that any system plugins related to javascript libraries, apart from the "MooTools Upgrade" plugin (which is required) has been disabled and try running jUpgrade again.

"Collation error"

All tables must have the collation of utf8_general_ci , and all applicable columns within those tables must have that collation as well.