Troubleshooting

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

Downgrading the Jenkins plug-in

To use an older version of the BMC AMI SQL Assurance for Db2 plug-in, do the following:

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

Missing required build step input

If you don't enter input for a required field in a build step during configuration,​​​ BMC AMI SQL Assurance for Db2 displays an error. You can still build the project, but the project will fail.

Java heap space error

If your job build fails with java.lang.OutOfMemoryError: Java heap space, increase the Java heap size in your Jenkins configuration.

Building projects with multiple plans or packages

• If you want to build a project with multiple plans or packages by using two or more BMC AMI SQL Assurance for Db2 - Analyze Static SQL plug-in steps, we recommend that you use one of the following methods: 

  • Configure a single project by using Object List File in the plug-in step. This lets you specify up to 100 plans or packages.

    Warning

    Important

    The memory storage limit might be exceeded if you specify a high number of objects in the Object List File. To resolve this issue, reduce the number of objects in the file.

  • Configure separate projects with a single plug-in step in each project. Build each project using a single pipeline.

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 SQL Assurance 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 SQL Assurance plug-ins require a minimum Jenkins version of 2.528.1 or later. For more information, see Planning. Attempting to install the BMC AMI SQL Assurance 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 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 SQL Assurance steps in the Add Build Step menu.
• Job configurations that rely on BMC AMI SQL Assurance 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.

This section contains guidelines to troubleshoot issues and errors that you might encounter when working with BMC AMI SQL Assurance 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 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 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, SMPE\/PropertiesFiles\/AMI_DevOps.properties).
• 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 about GitLab variables, see the GitLab documentation.
• If you want to run a pipeline or workflow with multiple plans or packages by using two or more Analyze Static SQL steps, we recommend you use one of the following methods:

  • In a config.yml file, use one of the analyzeStaticSql steps to specify the property key useObjectListFile: true and input the directory and file value in the objectListFilePath property key. This lets you specify up to 100 plans or packages.

    Warning

    Important

    The memory storage limit might be exceeded if you specify a high number of objects in the Object List File. To resolve this issue, reduce the number of objects in the file.

  • Configure a pipeline or workflow with multiple stages that each run a single analyzeStaticSql step and perform conditional checks to advance to the next stage.

Variable name conflicts with JCL syntax

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

Azure DevOps errors

• 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 doesn't 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, perform the following steps:

  • Make sure that you're not running the SELinux in enforcing mode. This mode prevents the container from running as root, which BMC AMI SQL Assurance 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 errors

  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: |
      staticSQL_plan  Azure/Test_config.yml
    displayName: 'SQL Assurance - Analyze Static SQL plan'

  The following error is displayed:

  /__w/_temp/4d0aca28-9b58-47ce-9d02-52d599a9ad17.sh: line 1: static_sql_plan: command not found 

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

  - script: |
      step staticSQL_plan  Azure/Test_config.yml
    displayName: 'SQL Assurance - Analyze Static SQL plan'

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

  - name: Static SQL - Plan
    run: |
      static_sql_plan GHA/Test_config.yml

  The following error is displayed:

  /__w/_temp/6611ee89-4e87-4840-85af-fdd80e0ec951.sh: line 1: static_sql_plan: not found

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

  - name: Static SQL - Plan
    run: |
      step static_sql_plan GHA/Test_config.yml

  (BMC.DB2.SPE2501) If the step command is omitted, as shown in the following example:

  script:
    - echo "Static SQL - Package application step"
    - static_sql_pg SMPE/JL/SA_configs/JL_config_SA_both.yml

  The following error is displayed:

  $ echo "Static SQL - Package application step"
  Static SQL - Package application step
  $ static_sql_pg SMPE/JL/SA_configs/JL_config_SA_both.yml
  /bin/bash: line 195: static_sql_pg: command not found

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

  script:
    - echo "Static SQL - Package application step"
    - step static_sql_pg SMPE/JL/SA_configs/JL_config_SA_both.yml