Troubleshooting guide for the Developer Portal

Use this guide to help you diagnose and resolve Developer Portal issues in IBM® API Connect.

About

The following sections provide advice about how to diagnose and resolve some common problems. This information can help you to identify whether a specific IBM API Connect Version 10 component is failing, whether it's an environmental problem, and whether you should raise a support request. Some advice includes reviewing specific log files so you can narrow down the source of the problem.
Note: In the The Help icon.Help page of the API Manager, and API Designer user interfaces, click the Product information tile to find out information about your product and Git package versions. The API Designer product information is based on its associated management server, but the Git information is based on where it was downloaded from.
  1. Why am I having problems with my Developer Portal user interface?
  2. Why am I having problems installing Drupal 8 based custom modules or sub-themes into the Drupal 9 based Developer Portal?
  3. Are my upgrade issues related to custom Drupal modules or themes?
  4. Why am I having migration issues with non identical environments?

Why am I having problems with my Developer Portal user interface?

If you are having user interface (UI) problems, make the following checks:
  • Try clearing the cache from your browser, try using private browsing, and try using different browsers - see whether there are any differences in behavior.
  • Check your browser window size and screen resolution, and try increasing and decreasing the settings.
  • Investigate the browser developer tools console and network tabs, as they might provide some diagnostic clues.
  • Try clearing the Drupal caches from within the Developer Portal; see Clearing the server caches for details.

If you need to open a Service Request, along with the IBM API Connect MustGather Information logs, also include details of the time and date when the problem was reproduced. In addition, an export of the browser developer tools console and network output would be helpful.

Why am I having problems installing Drupal 8 based custom modules or sub-themes into the Drupal 9 based Developer Portal?

From IBM API Connect 10.0.3.0, the Developer Portal is based on the Drupal 9 content management system. If you want to install Drupal 8 custom modules or sub-themes into the Drupal 9 based Developer Portal, you must ensure that they are compatible with Drupal 9, including any custom code that they contain, and not using any deprecated APIs, for example. There are tools available for checking your custom code, such as drupal_check on GitHub, which checks Drupal code for deprecations.

For example, any Developer Portal sites that contain modules or sub-themes that don't contain a Drupal 9 version declaration will fail to upgrade, and errors like the following output will be seen in the admin logs:
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:34:49: check_d9_compat: Checking theme: emeraldgreen
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:34:49: check_d9_compat: ERROR: Incompatible core_version_requirement '' found for emeraldgreen
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:34:49: check_d9_compat: Checking theme: rubyred
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:34:49: check_d9_compat: ERROR: Incompatible core_version_requirement '8.x' found for rubyred
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:34:49: check_d9_compat: ERROR: Found themes incompatible with Drupal 9: emeraldgreen rubyred
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:34:49: check_d9_compat: ERROR: /tmp/restore_site.355ec8 is NOT Drupal 9 compatible
...
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:44:49: check_d9_compat: Checking module: custom_mod_1
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:44:49: check_d9_compat: ERROR: Incompatible core_version_requirement '' found for custom_mod_1
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:44:49: check_d9_compat: Checking module: custom_mod_2
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:44:49: check_d9_compat: ERROR: Incompatible core_version_requirement '8.x' found for custom_mod_2
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:44:49: check_d9_compat: ERROR: Found modules incompatible with Drupal 9: emeraldgreen rubyred
[     queue stdout] 14834 729319:355ec8:a7d29c 2021-09-04 20:44:49: check_d9_compat: ERROR: site1.com is NOT Drupal 9 compatible
To fix version compatibility errors, all custom modules and sub-themes should declare a core_version_requirement key in their *.info.yml file that indicates Drupal 9 compatibility. For example:
name: Example module
type: module
description: Purely an example
core: 8.x
core_version_requirement: '^8 || ^9'
package: Example module

# Information added by Drupal.org packaging script on 2020-05-31
version: '8.x-1.3'
project: 'example_module'
datestamp: 1590905415
This example specifies that the module is compatible with all versions of Drupal 8 and 9. For more information, see Let Drupal know about your module with an .info.yml file on the drupal.org website.

If you have a backup of a site that you need to restore and are getting the version compatibility error, but the module or theme *.info.yml file cannot be changed easily, then you can modify the site backup.

To modify the site backup, extract the it, edit the relevant files inside it, and then tar the backup file again. Note that this procedure will overwrite the original backup file, so ensure that you keep a separate copy of the original file before you start the extraction. For example:

  1. mkdir /tmp/backup
  2. cd /tmp/backup
  3. tar xfz path_to_backup.tar.gz
  4. Edit the custom module and theme files to make them Drupal 9 compatible, and add the correct core_version_requirement setting.
  5. rm -f path_to_backup.tar.gz
  6. tar cfz path_to_backup.tar.gz
  7. cd /
  8. rm -rf /tmp/backup

Are my upgrade issues related to custom Drupal modules or themes?

To enhance the functionality of your Drupal site, you might install additional modules or themes that are not provided by IBM. While these custom or third-party components can offer extended capabilities, they might also impact the core features and introduce compatibility issues during upgrades. Additionally, these modules or themes might not align with the newer versions of Drupal or IBM API Connect modules or might contain bugs or vulnerabilities.
Note: IBM Support does not cover issues caused by third-party components or custom modules or themes.
If your customization is causing upgrade failures, consider the following steps:
Note: Always ensure that your custom modules and themes are compatible with the target upgrade version before proceeding.
  1. Back up your customization and site configuration using the exporting feature. For more information, Exporting and importing custom themes and site configuration.
  2. Temporarily switch themes - set the site theme to connect_theme and the admin theme to claro.
  3. Disable or temporarily remove the problematic modules.
  4. Proceed with the upgrade.
  5. Reapply and retest your customization after a successful upgrade
For more information about locating your custom modules and themes, see How to find your custom modules and themes on your Developer Portal.

For more information about upgrading your Developer Portal, see Preparations for upgrading your Developer Portal to Drupal 11.

Why am I having migration issues with non identical environments?

When exporting and importing custom themes and site configurations, ensure that the source and target Drupal environments are as closely identical as possible. Diverse environments might often cause migration failures or unexpected behavior. Always ensure that the configurations, enabled or disabled modules, or themes on both environments are identical and the database schema on the target environment is up to date.

You can review each environment in Admin > Reports > Status report.

For more information about exporting or importing custom themes and site configuration, see Exporting and importing custom themes and site configuration.