Developer Troubleshooting

This guide covers issues developers may encounter when working on RADIUSS Shared CI.

Component Development

Component Validation Errors

Error: Component has invalid spec

When this occurs: When publishing component to catalog (at tag push time)

Causes:

  • Invalid input type

  • Missing required spec fields

  • YAML syntax errors in spec section

Solution:

Validate component structure:

# templates/component-name/template.yml
spec:
  inputs:
    input_name:
      type: string          # Valid: string, number, boolean
      description: "..."    # Required
      default: "value"      # Optional
---
# Component implementation below

Error: Required input 'input_name' not provided

When this occurs: When user includes component in their pipeline (before pipeline execution)

Cause:

User didn’t provide required input or provided wrong type.

Solution:

Check component usage matches spec. GitLab validates inputs against component spec before running pipeline.

Component Not in Catalog

Issue: Component doesn’t appear in CI/CD Catalog after tagging

Checklist:

  1. Tag was synced to GitLab (after being pushed to GitHub):

  2. Repository has catalog metadata in README

  3. Component template.yml is valid

  4. GitLab 17.0+ instance

Solution:

Check catalog status at: https://lc.llnl.gov/gitlab/explore/catalog

If missing, verify tag exists on LC GitLab and re-push if needed.

Repository and Mirroring

Branch Not Mirrored to LC GitLab

Error: Project 'radiuss/radiuss-shared-ci' reference 'feature-branch' does not exist

Reference not found on LC GitLab

Cause:

Development branch does not exist on GitHub or hasn’t been mirrored to LC GitLab yet.

Solution:

  1. Push branch on GitHub

  2. Wait for mirror sync (usually a few minutes), alternatively trigger manual sync if you have access

  3. Verify on LC GitLab: https://lc.llnl.gov/gitlab/radiuss/radiuss-shared-ci/-/branches

Mirror Sync Delays

Issue: Changes not appearing in LC GitLab

Solution:

Check mirror status and force sync if needed (requires maintainer access).

Typical sync time: 5-30 minutes after GitHub push. If delays persist, contact maintainers to check mirror health (mirroring can be paused after inactivity).

Legacy Compatibility

Legacy Include Not Found

Error: Include file 'pipelines/dane.yml' not found

Causes:

  1. Invalid ref: value

  2. File path typo

  3. Version doesn’t exist on LC GitLab

Solution:

Check file exists at ref:

https://lc.llnl.gov/gitlab/radiuss/radiuss-shared-ci/-/blob/<ref>/pipelines/dane.yml

Empty Custom Directory Error

Error: Invalid character \x1b looking for beginning of value

Empty CUSTOM_CI_BUILDS_DIR error

Cause:

CUSTOM_CI_BUILDS_DIR set to empty string in .gitlab/custom-jobs-and-variables.yml.

Solution:

Comment out the line or provide valid path:

variables:
  # CUSTOM_CI_BUILDS_DIR: ""              # Comment out
  CUSTOM_CI_BUILDS_DIR: "/path/to/dir"    # Or set valid path

Getting Help

If issue isn’t covered here:

  1. Check user troubleshooting: Troubleshooting

  2. Search existing issues: https://github.com/LLNL/radiuss-shared-ci/issues

  3. Ask in PR: If working on contribution, ask in pull request

  4. Open new issue: Provide:

    • Development environment (GitLab version, branch)

    • Component or feature being developed

    • Error messages and logs

    • Steps to reproduce

See Also