Skip to main content
Blackboard Help

READ ME Before Running the Updater

Certain tasks need to be accomplished and settings checked before running the installer / updater. Server software must meet certain requirements in order to run the installer successfully.

For all platforms operating in a load-balanced environment, the Blackboard Application must be shut down on all the Application Servers for all upgrades. Upgrading one Application Server while another is running can cause database corruption on all platforms.

Upgrading Server Software


  • The database is run on a separate server when using two or more servers. In a Windows environment, the appropriate client tools for the database must be installed on the Application server or servers when using a configuration with two or more servers.
  • If running on Windows, when installing the Java SE Development Kit (JDK), make sure that both the JDK and the JRE components are installed to different locations. Also, ensure that there are no spaces in the path name to either the JDK or the JRE.
    • Shut down Bb-Services
    • Install recent version of the Java SE JDK, at least version 7u7
    • Change the JAVA_Home environment variable
    • Change the config\bb-config.properteries, and

If running on Windows, support for .NET APIs and .NET Building Blocks has been removed from Blackboard Learn in Release 9.1. If you are using .NET APIs and Building Blocks, they will not work in Release 9.1. Replace them with comparable Web Services and Java Building Block APIs. For more information about the available APIs, see the API documentation.

Linux and Solaris

  • The database is run on a separate server when using two or more servers. For Linux and Solaris configurations, the database client tools are shipped with the application and must not be installed separately.
  • If running on Solaris, ensure that the Swap space for the operating system is 0.5 – 1.5 times the amount of physical RAM on the server. For more information, see

When You Have a New License

If you have a license for Blackboard Learn 9.1 Blackboard Learning SystemTM - Basic Edition or Blackboard LearnTM - Basic Edition, you must first obtain an Enterprise license to upgrade to SP10. Contact your Blackboard learn account representative to transition to an Enterprise license.

When you have a new license, save the new license file in the same directory as the updater. Be sure not to confuse the new license with the old license file.

During the upgrade, select Provide new License file when prompted by the installer.

Cautions and Tips for Upgrading

SQL Server 2008 Settings

If you are running Learn 9.1 in a Windows environment, a successful installation or upgrade to SP10 requires SQL Server 2008. If your database server is upgraded from a previous SQL Server version (2005 or older) to meet this requirement, set the database Compatibility level to SQL Server 2008 (100) for all databases. The setting is located under Options in Database Properties.

Content Editor – Math Editor Image Service

To resolve broken math equation images when using a separate Image Service Host over SSL, generate a new self-signed certificate where the CN= matches the FQDN (fully qualified domain name) that appears in the Image Service Host. This new certificate should also be imported into the JDK keystore at JAVA_HOME/jre/lib/security/cacerts.

Warning for Customizations and Configuration

Running the Updater on an existing system will reset many back-end and user interface customizations. Examples and warnings describing specific known issues are included here.

Examples of affected back-end settings include:

  • JAVA_HOME system environment variable
  • SSL and custom authentication settings
  • Settings in the,, and wrapper.conf files

Examples of affected user interface settings and other affected areas include:

  • Course Settings (which control the Course Menu)
  • Building block availability
  • API hosts information
  • Module and Tab availability, role settings, and custom layouts

Customizations will need to be reapplied after the upgrade. To make this process easier, create a detailed document outlining all existing customizations.

Any configuration files removed by the upgrade will be placed in the blackboard_directory>/backups/<upgrade_timestamp> directory. Use these files as a guide when updating the new configuration files to reapply your previous customizations.

Mashups, Building Blocks, Blackboard Mobile and Firewall Warning

Bidirectional communication to Web Services that control the APIs for mashups, some Building Blocks, and Blackboard Mobile is required. If you are running Blackboard from behind a firewall as a test server or for security reasons, you will need to open the firewall to use these features. To open bidirectional communication to Web Services, you must configure your firewall to allow responses from the API hosts. Information from the hosts is available at these locations. Known ports are listed.

Echo 360 Warning

The Echo 360 Building Block supporting the free, limited-use access to Echo Personal capture and publishing capability is no longer be bundled with Blackboard Learn. Those institutions that have downloaded this Echo360 Building Block previously and are actively using it may continue to do so with support from Echo360. However, no new instances will be permitted or supported. Echo360 recordings can still be integrated into a Learn course using links. For clarification, Echo360 will continue to integrate with this and prior Blackboard Learn releases so learning content captured with a paid version of the Echo solution will accessible using Blackboard solutions. To learn more about how your school can work with Echo360’s Lecture Capture solutions, visit their website at

NBC Learn Warning

The NBC Learn Building Block will not longer be bundled with Blackboard Learn in SP10. Upgrading will have no affect on this Build Block if it has already been installed.

SafeAssign Warning

Institutions choosing to archive courses from a legacy production installation and then restore the courses to a new 9.1 instance will lose some of the data associated with SafeAssign, specifically SafeAssignments in restored courses and the student submissions to those SafeAssignments will be inaccessible. In addition, this option could potentially create a privacy issue where some students would be able to see submissions that are not their own.

To avoid these issues, when SafeAssign is heavily used, Blackboard recommends that one of the other two upgrade paths be selected: In-Place Upgrade or Fresh Install – Data Migration. 

If your institution does choose the archive/restore option, you need to have the existing SafeAssign institution database copied from the previous installation to the new installation.

A new SafeAssign registration is required for the new installation before restoring courses and using SafeAssign. Do not copy the file to the new installation and use the SafeAssign building block. Your data will become corrupted.

Please open a ticket with Client Support to request this copy after the new production installation is complete but before you restore courses.

Custom Themes Warning

Significant changes were made to the application markup and CSS in Release 9.1 to support new features and accessibility standards. These changes can cause customized themes and color palette changes created in earlier releases to malfunction as well as fail to apply styles to new features.

Beginning in SP10 a Theme DIFF Tool is available that compares two themes "in place" on your Blackboard Learn server using your theme handles. You can also run the tool on a non-blackboard machine comparing two themes, either zipped or expanded that you have downloaded from your Learn instance. The Theme DIFF Tool is available from Edugarage.

Comments have been added to the CSS files to make them easier to read and understand. These comments identify new elements and elements that are no longer used. Extraneous sectors have been removed.

Important Note about Adaptive Release

To ensure that Adaptive Release rules function correctly, additional steps may be required for courses created prior to Blackboard Learn Service Pack 6.

In the majority of cases it’s sufficient to remove these permissions manually from the Course Files. Instructors can perform this on a file-by-file basis where adaptive release control is required only on a small number of files, or permissions can be reset for the entire course.

Resetting all permissions to default using the user interface involves briefly permitting all course users access to the files in order that permissions can be revoked on all sub-directories and files in one step. In a course requiring adaptive release control of large numbers of files:

  1. In the course Control Panel, go to course Files.
  2. At the top of a page, access the drop-down menu for the course files directory. It will be labeled Files: <courseid>
  3. Click Permissions from the drop-down menu.
  4. Click Add Course User List.
  5. Select All Course Users.
  6. Select Read permission.
  7. Check the box to Overwrite the existing permissions.
  8. Click Submit.
  9. Find the newly created All Course Users list, and click Delete from the drop-down menu. Click OK to remove permissions from all sub-folders and files.
  10. You should be left with three user list permissions (unless you have previously created any custom instructor roles, in which case there will be more than three). Course Builder, Instructor and Teaching Assistant all with full manage permissions.

These instructions will be slightly different if you have licensed the Content Collection.

Note: In rare cases, additional steps may be required. The adaptive release functionality requires file links to exist in a table called cms_resource_link. Depending on your Learn version history, in some cases, these rows may not exist and so a course copy or an archive/restore will be required for all content items to function properly with adaptive release.

Previous Content Management Clients Warning

If your institution is planning to upgrade from Blackboard Learn 9.0 or earlier please be aware of possible complications with content management. Clients who have previously licensed the content management capabilities, but no longer have such a license, may encounter problems when upgrading to Release 9.1. This occurs because of lingering schemas in the database that require a content management license. Because of these lingering schemas, the installer is unable to upgrade the database properly and will fail.

If your institution’s database has lingering schemas from a previous content management license you must obtain the appropriate uninstaller script from Blackboard Client Support to remove these schemas before upgrading to 9.1.

Load-Balanced Systems Warning

The updater must be run on each application server and the Collaboration server on a load-balanced system. After running the updater the first time, choose the Update an App Server for all other application servers and the Collaboration server. This option will upgrade the application files without making any of the database changes.

For all platforms operating in a load-balanced environment, the Blackboard application must be shut down on all the application servers for all upgrades. Upgrading one application server while another is running can cause database corruption on all platforms.

Upgrades may fail if Port 80 is being used. The installer validates that it can complete installation and start services without conflict by verifying that the ports configured for Blackboard are not in use to avoid startup failures. The ports are checked against the load- balanced hostname bbconfig.webserver.fullhostname, where the load-balancer may still be responding during the upgrade. To avoid this error:

See KB article Upgrade Fails with Port 80 Already in Use for more details.

Oracle 11gR2 Errors

Oracle 11gR2 contains two bugs that cause errors.

The first bug displays errors when importing content or restoring course packages. To prevent this error, as an Oracle user, run the following command:

alter system set "_optimizer_push_pred_cost_based"=false scope = both; alter system set cursor_sharing=EXACT scope=both;

The second bug returns an error that reads:


To prevent this error, apply the Oracle patch bundle number 9259407. This issue is resolved in Oracle