Skip to content

BuildStreaM Issues

Issues related to BuildStreaM pipeline execution, GitLab integration, catalog validation, and image deployment.

Health Check stage failing

Symptom

Health Check stage is failing in the BuildStreaM pipeline.

Cause
  • GitLab target IP and host IP of the BuildStreaM API server are not reachable from each other
  • BuildStreaM containers are not running properly
Resolution

  1. Ensure the GitLab target IP and BuildStreaM API server are in the same subnet.

  2. Verify that the omnia_build_stream container and the omnia_postgres and playbook_watcher services are running on the OIM node:

    Run on: OIM host
    systemctl status omnia_build_stream.service
systemctl status omnia_postgres.service
systemctl status playbook_watcher.service

  3. If there are failures in any of the containers, capture and verify the logs from journalctl:

    Run on: OIM host
    journalctl -u omnia_build_stream --no-pager
journalctl -u omnia_postgres --no-pager

API Registration stage failing

Symptom

API-Registration stage is failing in the BuildStreaM pipeline.

Cause
  • Maximum client limit reached for BuildStreaM API server registration
  • Other API registration errors

Note

Currently, only one client can be registered with the BuildStreaM API server.

Resolution

  1. If you encounter the max_clients_limit_reached error:

    • Either run the pipeline from the already registered client
    • Or perform the cleanup_gitlab and reconfigure GitLab using the playbook

  2. For other non-successful API responses, on the OIM, check the authentication logs at /<nfs-dir>/omnia/log/build_stream/auth.log for detailed error information.

Token Generation stage failing

Symptom

Token-Generation stage is failing in the BuildStreaM pipeline.

Cause
  • Token generation failed due to authentication issues
  • Token generation failed due to network issues
Resolution

On the OIM, check the authentication logs at /<nfs-dir>/omnia/log/build_stream/auth.log for detailed error information.

Parse Catalog stage failing

Symptom

Parse-Catalog stage is failing in the BuildStreaM pipeline.

Cause
  • Invalid JSON schema format
  • The catalog_rhel.json structure does not match the expected catalog schema
Resolution

Create Local Repo stage failing

Symptom

Create-Local-Repo stage is failing in the BuildStreaM pipeline.

Cause
  • Playbook execution failed
  • Configuration issues in local_repo_config.yml
Resolution

  1. If there are issues with playbook execution, the log path is available from the API response. Check the logs at the path specified in the log_file_path field.

    Example API response format:

    Example API response format
    {
    "stage_name": "create-local-repository",
    "stage_state": "FAILED",
    "started_at": "2026-03-11T10:07:58.906785+00:00Z",
    "ended_at": "2026-03-11T10:49:20.639894+00:00Z",
    "error_code": "PLAYBOOK_EXECUTION_FAILED",
    "error_summary": "Playbook exited with code 2",
    "log_file_path": "/nfs/omnia/log/build_stream/5a4f69f4-44df-42eb-b88b-1583ea2610a8/local_repo.yml_20260311_171630.log"
}

  2. Verify the configuration settings in local_repo_config.yml.

  3. After fixing the configuration issues, re-run the pipeline.

Build Images stage failing

Symptom

Build Images stage is failing in the BuildStreaM pipeline.

Cause
  • Playbook execution failed
  • Catalog does not have predefined functional groups
Resolution

  1. Ensure the catalog has the predefined functional groups. For the supported functional groups, see the BuildStreaM deployment guide.

  2. If changes are required in the catalog, make the necessary modifications to the catalog.

  3. After fixing catalog issues, re-run the pipeline.

Deploy Images stage failing

Symptom

Deploy Images stage is failing in the BuildStreaM pipeline.

Cause
  • Playbook execution failed
  • The functional groups listed in the PXE mapping file do not adhere to functional groups in the catalog_rhel.json
Resolution

  1. Check the log path from the API response for detailed error information.

  2. Ensure the functional groups listed in the PXE mapping file matches the functional groups defined in the catalog_rhel.json.

  3. After making necessary modifications to the PXE mapping, re-run the pipeline manually.

Retry button not displayed

Symptom

The Retry button is not displayed for failed pipeline stages, including deploy, restart, and validate operations.

Cause

The Retry button may not appear in certain failed pipeline stages due to GitLab issues.

Resolution

  1. Initiate a restart from the parent pipeline to resolve this issue.

  2. This action restarts the entire pipeline from the beginning, allowing all stages to execute again.

Info