Troubleshooting

This guide provides a basic overview troubleshooting for commonly occuring problems and basic setup of the environment.

basic pypts environment setup.

Issues can often occur due to missing libraries, conflicting versions or conflicting elements in the environment.

If you come into any difficulties, making a fresh virtual environment is recommended. To do so, create a new virtual environment in the project folder in a similar position as this.

my_project/
├── .venv/
├── /src/pypts/
├── ├── __init__.py
├── ├── __main__.py
├── ├── recipes/
├── ├── ├── simple_recipe_GOLDEN_COPY.yml
├── tests/unit_tests/
│   └── other_test_modules.py
└── README.md

Activate the environment and install the package within the environment.

# Install in development mode
pip install -e .

# Or install normally
pip install .

Before using pypts, you may need to install the following system dependencies for PySide6 (Qt GUI framework):

Note

Python 3.14 requires PySide6 6.10 or newer. The project’s historical PySide6==6.9.1 pin has no Python 3.14 distribution, so environments using Python 3.14 must bump that dependency to at least the 6.10 release line.

sudo dnf install libxcb libxcb-devel
sudo dnf install xcb-util xcb-util-wm xcb-util-keysyms xcb-util-image xcb-util-renderutil

Recipe-related issues.

Recipe language 2.0.0 requires a header document and at least one complete sequence document. Start from the parser-tested example instead of copying an isolated fragment:

Valid recipe-language 2 structure

# SPDX-FileCopyrightText: 2026 CERN <home.cern>
# SPDX-License-Identifier: CC-BY-SA-4.0
---
name: Recipe language 2 documentation example
version: "1.0"
recipe_version: 2.0.0
description: Demonstrate canonical version 2 syntax and typed mappings.
main_sequence: Main
continue_on_error: false
report: overwrite
report_name_include_serial: true
test_package: acceptance.tests
globals:
  target: 12
  saved_result: null
---
sequence_name: Main
description: Run a measurement and then the calibration sequence.
parameters: {}
outputs: {}
locals:
  expected: 12
  measured: null
setup_steps: []
steps:
  - steptype: PythonModuleStep
    step_name: Measure channels
    description: Exercise every input mapping and representative outputs.
    id: measure-channels
    skip: false
    critical: true
    continue_on_error: false
    action_type: method
    module: measurements.py
    method_name: measure
    input_mapping:
      channels: {type: direct, value: [0, 1], indexed: true}
      expected: {type: local, local_name: expected}
      target: {type: global, global_name: target}
      transform: {type: method, value: normalize}
    output_mapping:
      passed: {type: passfail}
      exact: {type: equals, value: 12}
      bounded: {type: range, min: 10, max: 14}
      measured: {type: local, local_name: measured}
      saved: {type: global, global_name: saved_result}
      chart: {type: image}
  - steptype: SequenceStep
    step_name: Calibrate
    description: Run a nested sequence and use its aggregate verdict.
    sequence: {type: internal, name: Calibration}
    input_mapping: {}
    output_mapping:
      result: {type: passthrough}
      stored: {type: local, local_name: measured}
teardown_steps: []
---
sequence_name: Calibration
description: Wait for the equipment to stabilize.
parameters: {}
outputs: {}
locals: {}
setup_steps: []
steps:
  - steptype: WaitStep
    step_name: Stabilize
    description: Wait before returning to the caller.
    input_mapping:
      wait_time: {type: direct, value: 1}
    output_mapping: {}
teardown_steps: []

If validation fails, use the diagnostic code, field path, and source position. The most common migration failures are an old or missing recipe_version, a lowercase step discriminator, a literal input without type: direct, a missing description, or the removed sequence serial_number field. See Recipe YAML Format for migration guidance and the generated Recipe Language 2.0 Reference for exact fields.

ModuleNotFoundError

Ensure test_package is properly named in the recipe and that the method_name properly name the specific function to run.

Note

As of 13/08/2025, the run_tests.py will run through all the tests, but will not catch lack of test_package which would appear as an error during runtime.

Import Errors: Make sure all directories have __init__.py files

Path Issues: With test_package, use a module path relative to the package. Nested paths are supported.

Package Installation: Ensure your package is installed in the Python environment where you’re running pypts

Failing test despite reading a passing value: Ensure the datatype that is compared against is equal to the read value, i.e. string cannot be compared to integer.