If you are a Managed Hosting customer, this topic doesn't apply to you.

This topic lists some of the common problems that occur during installation and possible solutions.

Note that often the fastest resolution to an installation problem may be a Client Support call away.

Contact Blackboard Client Support

For information about contacting Blackboard Technical Support, log in to Behind the Blackboard.

Blackboard Support Site and Knowledge Base

The Blackboard Knowledge Base, which is accessible through Behind the Blackboard, includes several articles that may address your problem. If a login for Behind the Blackboard is unavailable, please contact a Blackboard Account Manager.

Troubleshoot

Discovery of root cause

The installer creates a log file named bb_installer_log.txt. This file is found in the blackboard logs directory accessible under the Blackboard install directory.

If the installer fails, check the log file to help determine the problem. The log file includes a considerable amount of information about the installation process. Each time the installer is run, the attempt is appended to the log file. Make sure to focus on the latest attempt, which will be last entries in the log file. Attempts and activity is time stamped.

Because of the amount of information in the log file, the problem may not be immediately apparent. Try searching for the following strings at the bottom of the installation log: BUILD FAILED or Root Cause. Look closely at the log file both above and below the search string (BUILD FAILED or Root Cause) for the reason the installation failed.
If the log file does not help diagnose the problem, keep a copy of the file as Client Support will use it to diagnose the problem. Contact Blackboard Learn Client Support by logging in to Behind the Blackboard.

Common issues

Pages won't load

If certain pages in Blackboard Learn will not open or take too long to load, do the following to resolve this issue:

Windows

1. Modify the Windows registry and add the following keys:

  1. Select Start > Run > regedit.
  2. Go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters.
  3. Add the following two values:

    TcpTimedWaitDelay=dword:0000001e
    MaxUserPort=dword:0000fde8

    These are DWORD values. After they have been created, you can double-click to edit their Decimal values.

2. Turn off Full Text Search on SQL Server:

  1. Select Start > Administrative Tools > Services.
  2. Stop and disable Microsoft Search and SQL Server Full Text Search service.

3. Turn off all network card offload functionality (disable TCP Checksum Offload):

  1. Right-click My Computer > Properties > Hardware Tab > Device Manager.
  2. Select Network Adapters > right-click Broadcom BCM5708S NetXtreme II GigE > Properties.
  3. Select Advanced Tab > Property: Checksum Offload > Value: None.
  4. Advanced Tab > Property: Large Send Offload > Value: Disable.

4. Disable network card power saving features:

  1. Right-click My Computer > Properties > Hardware Tab > Device Manager.
  2. Select Network Adapters > right-click Broadcom BCM5708S NetXtreme II GigE > Properties.
  3. Select Management Tab > Uncheck Allow the computer to turn off this device to save power > OK.

5. Reboot the system

6. Turn off the TCP Chimney:

  1. Select Start > Run.
  2. Type cmd, and then press ENTER.
  3. At the command prompt, type Netsh int ip set chimney DISABLED, and then press ENTER.

7. To dynamically turn on TCP Chimney by using the NETsh.exe tool:

  1. Select Start > Run.
  2. Type cmd, and then press ENTER.
  3. At the command prompt, type Netsh int ip set chimney ENABLED, and then press ENTER.

To learn more, consult the Microsoft Knowledge Base article 912222.

Database connection failure

Incorrect database username/password combinations will prevent the Learn installer from connecting to the backend database and completing the installation.

UNIX

  • Ensure that the password for the Oracle SYSTEM user is correct.
  • Ensure that the SID is accurate and matches your listener settings for connecting to the database

Windows

Installation Failure Due to Strict Password Requirements (SQL Server)

  • For an installation with SQL Server, the installation may fail because of the strict parameters for password requirements. The user will receive the following message: Password validation failed. The password does not meet Windows policy requirements because it is too short.
  • To override or reset the password requirements, complete the following steps:
  1. Create a text file mycustom.properties and add the following line to it (substitute the right value):

    bbconfig.database.jreport.password=pAssw0rd

  2. Run the installer as follows (text in caps should be filled in as appropriately):

    java -jar bb-as-PLATFORM-VERSION.jar -config mycustom.properties

Q2 2016 common issues

The following section highlights a few caveats and tips to help install Q2 2016, as well as a few common errors and the known work-around or fix.

  • Always run CMD window in Windows as an Administrator
  • Running with -d is equivalent to gradle --debug
  • Running with -i is equivalent to gradle --info
  • The installer downloads and installs gradle for you
  • The installer configures the installation based on your properties
  • If installing on Linux, must NOT be run from root
  • -c <configuration file> requires the full absolute path
  • Properties file and license must not be in the Blackboard Installation directory
  • Passwords must be in plain text

Collab server is missing

Operating System: Windows
Process: Upgrade

Description:

The upgrade process attempts to remove the Windows Services prior to upgrade. If the Collab service is non-existent, this will cause the upgrade to fail

Symptom:

* What went wrong: Execution failed for task ':install:legacy:CollaborationServiceUninstall'. > Process 'command 'C:\blackboard\apps\service-wrapper\bin\UninstallService.bat' 'finished with non-zero exit value 1

Fix:

Create a dummy service and re-run the upgrade. sc create BBLEARN-Collab binpath= c:\windows\system32\NewServ.exe

Change in user-created directory handling

Operating System: All
Process: Upgrade

Description:

The Blackboard Learn system contains user-created directories under [BB_HOME]. The expected behavior is to move user-created directories to the backup/<upgrade-date-time> directory. After upgrading to 9.1 Q2 2016, the user-created directory persists.

Symptom:

User-created directory is still located in the blackboard home directory.

Fix:

No fix or work-around at this time.

Installing on an offline server

Operating System: All
Process: All

Description:

Installation of Blackboard Learn now requires Gradle. As part of the installation script, the install script uses gradlew to start the process. Gradlew then downloads Gradle 2.9 and installs it for the installation process. However, many clients prefer to install on a server that is not connected to the external network.

Symptom:

The installer cannot download and install Gradle.

Fix:

The best fix is to configure gradlew to "download" the installer from an accessible location, like a local directory. To configure gradlew, you must locate the gradle-wrapper.properties file. In this file, you should see an entry called distributionUrl. Change this value to an absolute path or a path relative to the location of the gradle-wrapper.proprties file. The path should include the zip file. Then simply put gradle-2.9-bin.zip in that location. Here is an example:

distributionUrl=/usr/local/gradle/gradle-2.9-bin.zip
distributionUrl=../gradle/gradle-2.9-bin.zip

More on Gradlew