Troubleshooting

This section contains guidelines to troubleshoot issues and errors that you might encounter when working with BMC AMI DevOps for Db2 specifically when using Jenkins.

General error

If you don't enter input for a required field of a build step during configuration, BMC AMI DevOps displays an error. You can still build the project, but the project fails.

Using an older version of the BMC AMI DevOps plug-in

To use an older version of the BMC AMI DevOps plug-in in Jenkins, follow these steps:

1. Manually reinstall the .hpi file of the older version. 
2. Restart the Jenkins server when no jobs are running.

Handling Bad Message 414 errors

Schema rule–related issues

• ​​​If you have a problem running your Jenkins pipeline with your rule set in the BMC AMI DevOps Schema Mgmt for Db2 - Schema Standards build step, set Violation Response to WARN. This allows the pipeline to run all steps to completion until you can correct your schema definition.

• If you receive a host variable or SQL error for your rule, you can set your rule to inactive in BMC AMI Command Center for Db2 rule editor. This allows the pipeline or project to run to completion until you can resolve the error with the rule.

Handling errors when running a sample configuration

If you get the following error when trying to run a BMC-provided sample configuration, open the Jenkins project or pipeline configure page and click Save or Apply. Then rerun the project or pipeline. For more information about configuring a sample project or pipeline, see To use the configuration provided in the sample project.

Configuration best practice: handling manual config.xml updates

• When you manually copy or replace a job’s config.xml file directly in the Jenkins job directory (for example, through the file system), we recommend that you re-initialize the job configuration before running the next build. Manually updating the config.xml modifies only the stored XML file. It doesn't activate Jenkins’ lifecycle methods (such as the job's Constructor or associated DescriptorImpl methods). These methods are responsible for loading job parameters, initializing plug-in data, and ensuring the project is correctly constructed in memory.
• If you skip this re-initialization step, Jenkins may attempt to run the job with incomplete or uninitialized configuration data, which can lead to runtime failures, including NullPointerException errors.

• To ensure job stability and prevent runtime errors when you have manually modified or copied a job's config.xml, complete the following steps:

  1. Copy or replace the config.xml file in the job directory.
  2. Restart Jenkins or click Reload Configuration from Disk under Manage Jenkins.
  3. In the Jenkins UI, open the job’s Configure page.
  4. Click Save or Apply.

  This sequence forces Jenkins to call the necessary lifecycle methods, ensuring the job is fully initialized in memory before any subsequent build. For more information about configuring a sample project or pipeline, see To use the configuration provided in the sample project.

Jenkins and Java version requirements

To ensure stability and proper operation, the updated BMC AMI DevOps plug-ins require minimum supported versions of both Jenkins controller and agents and Java running the environment.

The following scenarios describe potential version conflicts and the required corrective actions.

Installing the updated plug-ins on an unsupported Jenkins version

The BMC AMI DevOps plug-ins require a minimum Jenkins version of 2.528.1 or later. For more information, see Planning.  Attempting to install the BMC AMI DevOps plug-ins on an older Jenkins version results in the following error during the installation process:  

Action: Upgrade Jenkins to version 2.528.1 or later.

Installing and running the updated plug-ins with a valid Jenkins version and a controller Java version ​while the agent Java version is earlier than required

The Jenkins controller is running on a supported Java version (for example, Java 21), but one or more execution agents are running on an earlier version of Java (for example, Java 17). Builds running on the outdated agent fail with Java compatibility errors. Jenkins console log displays message BMCAMA00056E, and the agent system log displays java.lang.UnsupportedClassVersionError, indicating a class compiled for a later Java version is running on an agent with an older Java version.

 An example of the Jenkins console log is as follows:

Action: Upgrade the agent Java version to match the controller Java version (Java 21 or later), because Jenkins requires that all agents run on the same Java version as the controller.

Installing and running the updated plug-ins with a valid Jenkins version while the controller Java version is earlier than required

If you install the updated plug-ins on a supported Jenkins version while the Jenkins controller uses an older Java version (earlier than the minimum required version), Jenkins loads the plug-ins but omits critical functionality steps from job configurations. The plug-ins appear to install successfully in the UI, and Jenkins shows no installation errors under the plug-in names. However, the controller can't load the plug-in classes because they were compiled for a newer Java version. The following issues occur:

• Critical plug-in functionality is missing, including BMC AMI DevOps steps in the Add Build Step menu.
• Job configurations that rely on BMC AMI DevOps steps appear empty, because Jenkins can't load or render the associated components.
• The only indication of failure appears in the Jenkins system logs, which contain multiple initialization errors, including an UnsupportedClassVersionError.

Action: Upgrade the Jenkins controller Java version to Java 21 or later.

(BMC.DB2.SPE2304)

This section contains guidelines to troubleshoot issues and errors that you might encounter when working with BMC AMI DevOps for Db2 specifically when using Universal Connector.

Variable issues in Azure DevOps, GitHub Actions, and GitLab CI/CD

• For Azure DevOps and GitHub Actions: When you create a variable for a Linux directory path, the path value requires a backslash (\) escape character before each forward slash (/) path separator (For example, sample\/PropertiesFiles\/AMI_DevOps.properties).
• For Azure DevOps and GitHub Actions: When you create a variable with one of these special characters ($,&) in the value, the value requires a backslash (\) escape character before either of the special characters (for example, DB\$123, TBL\&A). This is applicable to the 'password' key-value as well.
• For GitLab CI/CD—when you create a masked variable, the value is limited to a minimum of 8 characters and these special characters (@, _, :, +). For more information on GitLab variables, see the GitLab documentation.

Variable name conflicts with JCL syntax

• When you create a variable name that is also used in JCL syntax or input keyword and then run the pipeline or workflow, the variable value replaces the syntax or keyword and ultimately causes the step to fail.

Missing unzip utility in first released image

• (BMC.DB2.SPE2307)If you receive this error: unzip: not found, while running the workflow in which you used the unzip step and the first released image, 13.01.00.0001-GA, then either remove the unzip step from the workflow or change the workflow image and rerun the workflow. The first released image did not include the unzip utility and should not be used with new features after the first released image.

Azure DevOps errors

• (BMC.DB2.SPE2504)The Azure DevOps pipeline might fail in the Authentication step with the following error: BMCAMA00058E Field executionIdentifier value cannot have more than 4 properties , this can occur for the following reasons:

  • Your config YAML file contains extra properties in executionIdentifier. The allowed properties are PipelineName, RunNumber, RunBy, and RunMode. If an additional property is present, remove it from your config YAML file.
  • The username defined in your Azure DevOps Organization Settings includes a comma (for example, “last name, first name”). The comma causes the processing of the Azure DevOps system variable Build.RequestedFor in the executionIdentifier property key’s RunBy property to fail.

     If this occurs, perform one of the following corrections:

  • • Update the sed Linux command for RUNBY_VALUE in the pipeline YAML file so that it removes the comma. For example:
      sed -i "s/RUNBY_VALUE/$(echo $(Build.RequestedFor) | sed 's/,//g')/" <config YAML file>
    •  Create an Azure DevOps variable named RUNBY_VALUE, set the value as your username (without a comma), and update the sed Linux command for RUNBY_VALUE in the pipeline YAML file as follows:
      sed -i "s/RUNBY_VALUE/$(RUNBY_VALUE)/" <config YAML file>
    • Remove the (RunBy=RUNBY_VALUE) property in the executionIdentifier property key defined in the config YAML file.
  • When you define an Azure DevOps pipeline, we recommend using the BMC AMI SQL Assurance step as a separate script. Running a bash or shell command after the step might cause Azure DevOps to report the script execution result inaccurately. 

  • The Azure DevOps pipeline might fail with the following message in the Initialize container step because the container does not stay up. Disregard the time stamp and container ID.

    2023-10-05T12:25:21.5544536Z ##[warning]Docker container d83d7db2e08eaf1e401521baef9e8b9a724ced0bec7e4be1656fa4d2fa2ee432 is not in running state.
    2023-10-05T12:25:21.5606939Z ##[command]/usr/bin/docker exec  d83d7db2e08eaf1e401521baef9e8b9a724ced0bec7e4be1656fa4d2fa2ee432 sh -c "command -v bash"
    2023-10-05T12:25:21.6596835Z ##[error]Docker-exec executed: `sh -c "command -v bash"`; container id: `d83d7db2e08eaf1e401521baef9e8b9a724ced0bec7e4be1656fa4d2fa2ee432`; exit code: `255`; command output: `Emulate Docker CLI using podman. Create /etc/containers/nodocker to quiet msg.`, `Error: can only create exec sessions on running containers: container state improper`
    2023-10-05T12:25:21.6601435Z ##[section]Finishing: Initialize containers

    If this error occurs, then perform the following steps:

    • Make sure that you are not running the SELinux in enforcing mode. This mode prevents the container from running as root, which BMC AMI DevOps requires.
    • Change the SELinux security mode to permissive mode. This gives a warning when running the container as root, but allows the container to continue to run.
    • Restart the VM.
    • Rerun your pipeline.

  Step command omitted in pipelines or workflows

  If the step command omitted from your pipeline or workflow, a shell error of either command not found or not found is displayed. For more information, see the following tabs: 

  • Azure DevOps pipeline
  • GitHub Actions workflow
  • GitLab CI/CD pipeline

  If the step command is omitted, as shown in the following example:

  - script: |
      schema_standards_catalogMigrateProfileScope Azure/Test_config.yml
    displayName: 'Schema Standards with Catalog Migrate Profile source'

  The following error is displayed:

  /__w/_temp/700be3f0-9de6-4886-a461-d3543f4b9e33.sh: line 1: schema_standards_catalogMigrateProfileScope: command not found
  ##[error]Bash exited with code '127'.

  To correct this error, add the step command, as shown in the following example:

  - script: |
      step schema_standards_catalogMigrateProfileScope Azure/Test_config.yml
    displayName: 'Schema Standards with Catalog Migrate Profile source'

  If the step command is omitted, as shown in the following example:

  - name: Schema Standards Migrate Profile source step
    run: |
      schema_standards_catalogMigrateProfileScope GHA/Test_config.yml

  The following error is displayed:

  /__w/_temp/5af6affc-f6be-4bff-856d-943a315601b0.sh: line 1: schema_standards_catalogMigrateProfileScope: not found
  Error: Process completed with exit code 127.

  To correct this error, add the step command, as shown in the following example:

  - name: Schema Standards Migrate Profile source step
    run: |
      step schema_standards_catalogMigrateProfileScope GHA/Test_config.yml

  (BMC.DB2.SPE2504)

  If the step command is omitted, as shown in the following example:

  - schema_standards_ddl $CONFIG_FILE

  The following error is displayed:

  /bin/bash: line 210: schema_standards_ddl: command not found

  To correct this error, add the step command, as shown in the following example:

  - step schema_standards_ddl $CONFIG_FILE
  )))