Skip to main content

Troubleshooting

Solutions to common issues.

Analysis Issues​

Symbols Not Appearing Correctly​

Cause: Debug symbols not included in ELF file.

Solution: Add -g flag to your compiler:

CFLAGS += -g

For GCC, ensure you're not stripping symbols:

# Don't use -s flag during linking
arm-none-eabi-gcc ... -o firmware.elf  # Good
arm-none-eabi-gcc -s ... -o firmware.elf  # Bad - strips symbols

CI/CD Issues​

Build Fails During Onboarding​

Cause: Historical commits may have different build requirements.

Solutions:

  1. Ensure all build dependencies are installed
  2. Check if build scripts changed over time
  3. Reduce num_commits to skip problematic history

Reports Not Uploading​

Cause: Network or authentication issues.

Solutions:

  1. Verify API key is correct
  2. Test connectivity: curl https://api.membrowse.com/health
  3. Check CI logs for specific error messages

API Key Not Found​

Cause: Secret not configured correctly in CI.

Solutions:

  • GitHub Actions: Check Settings > Secrets > Actions
  • GitLab CI: Check Settings > CI/CD > Variables
  • Other CI: Check your CI system's environment variable or secrets configuration
  • Verify secret name matches exactly (case-sensitive)

GitHub Actions Issues​

Commit Message or Branch Not Displayed Correctly​

Cause: GitHub Actions performs a shallow clone by default, which may not include enough Git history for metadata detection.

Solution: Add fetch-depth: 0 to the checkout step in your analyze job:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0

PR Comments Not Appearing​

Causes and Solutions:

  1. Wrong workflow name in trigger:

    # Ensure this matches exactly
    on:
      workflow_run:
        workflows: [MemBrowse Memory Report]  # Must match the other workflow's name

  2. Missing permissions:

    permissions:
      pull-requests: write
      actions: read

  3. Fork PR: The two-workflow pattern is required for fork PRs

Workflow Not Triggering​

Cause: Workflow file syntax error or wrong trigger.

Solutions:

  1. Validate YAML syntax
  2. Check trigger conditions: 
    on:
      pull_request:  # Triggers on PR
      push:
        branches: [main]  # Triggers on push to main
  3. Ensure workflow file is in .github/workflows/

GitLab CI Issues​

MR Comment Not Appearing​

Causes and Solutions:

  1. Missing or invalid token: Ensure MEMBROWSE_GITLAB_TOKEN is set as a masked CI/CD variable with api scope. A project access token with the Reporter role is recommended.
  2. Comment job not running on MR pipelines: The comment job only runs on merge request pipelines. Check that your pipeline is triggered by $CI_MERGE_REQUEST_IID.
  3. Missing report artifact: The comment job depends on the analysis job's report artifact. Verify the analysis job completed successfully and that needs: is configured correctly.

Duplicate Pipelines Running​

Cause: Both a branch pipeline and a merge request pipeline trigger when pushing to a branch with an open MR.

Solution: Add $CI_OPEN_MERGE_REQUESTS == null to the branch rule on your build job:

rules:
  - if: $CI_MERGE_REQUEST_IID
  - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS == null

See the GitLab CI Setup for a full example.

Analysis Job Fails with "ELF file not found"​

Causes and Solutions:

  1. Ensure the build job is listed in needs: on the analysis job
  2. Verify the artifacts: paths: in the build job includes the ELF file
  3. Check that the MEMBROWSE_ELF path matches the actual build output

Self-Hosted GitLab Template Not Loading​

Cause: The include: project: syntax requires the template project to be on the same GitLab instance.

Solution: Use the remote URL instead:

include:
  - remote: 'https://gitlab.com/membrowse/gitlab-ci/-/raw/v1/membrowse.yml'

Architecture Issues​

Unsupported Binary Format​

Cause: MemBrowse currently supports only ELF binary format.

Solutions:

  1. Verify your file is in ELF format: file firmware.elf
  2. If your toolchain produces a different binary format, contact us to explain your use case and we will add support for it

Linker Script Parse Error​

Cause: Non-standard linker script syntax.

Solutions:

  1. MemBrowse supports GNU LD linker scripts (.ld) and IAR ICF files (.icf). Verify you are using one of these formats.
  2. Check for syntax errors in linker script
  3. Try simplifying the MEMORY section
  4. Contact us with the linker script if you need help

Getting Help​

If you can't resolve an issue:

  1. Check the GitHub Issues
  2. Request a demo to talk with the team