Improve error message for duplicate pipeline run names

[strickvl]

Summary

• Improve the error message when users try to run a pipeline with a duplicate run_name
• Handle duplicate run name errors directly in SQLZenStore where they occur
• Provide a user-friendly error message with actionable solutions
• Fix SQLAlchemy autoflush timing issue to ensure proper error handling

Problem

When users run a pipeline with a duplicate run name (whether from a config file, programmatically, or any other method), they get a confusing database error. The error can come in two forms:

1. A raw SQL IntegrityError (when using REST API):

RuntimeError: (pymysql.err.IntegrityError) (1062, "Duplicate entry 'test_run_name-6e23c0466cc4411c8b9f75f0c8a1a818' for key 'pipeline_run.unique_run_name_in_project'")

2. An EntityExistsError with a technical message

Additionally, there was a subtle SQLAlchemy autoflush timing issue where IntegrityErrors were being raised during _get_reference_schema_by_id calls instead of during the explicit session.commit(), preventing proper error handling.

Solution

This PR catches IntegrityError in SQLZenStore's _create_run method and provides a much more helpful error message with actionable solutions. It also fixes the SQLAlchemy autoflush issue to ensure errors are properly caught and handled.

Before (Raw SQL Error)

RuntimeError: (pymysql.err.IntegrityError) (1062, "Duplicate entry 'my_run-6e23c0466cc4411c8b9f75f0c8a1a818' for key 'pipeline_run.unique_run_name_in_project'")
[SQL: INSERT INTO pipeline_run ...]

After (User-Friendly Error)

Pipeline run name 'my_run' already exists in this project. Each pipeline run must have a unique name.

To fix this, you can:
1. Use a different run name
2. Use a dynamic run name with placeholders like: "my_run_{date}_{time}"
3. Remove the run name from your configuration to auto-generate unique names

For more information on run naming, see: https://docs.zenml.io/concepts/steps_and_pipelines/yaml_configuration#run-name

Changes Made

• Enhanced error handling in SQLZenStore's _create_run() method to catch IntegrityError and provide user-friendly messages
• Fixed SQLAlchemy autoflush issue by wrapping logs processing in session.no_autoflush to prevent premature IntegrityError during reference lookups
• Replaced mocked unit test with proper integration test that actually runs real pipelines twice with the same name
• Made error message more generic - removed specific mention of "config file" since run names can be set in multiple ways
• Updated integration tests to verify the fix works end-to-end with real pipeline execution

Test Plan

• Integration test verifies duplicate run names are properly detected when running real pipelines
• Integration test confirms EntityExistsError is raised (not raw IntegrityError)
• Integration test validates clear error message is shown to users
• All existing tests continue to pass
• Mypy type checking passes
• Formatting and linting checks pass

Technical Details

The key fix was addressing the SQLAlchemy autoflush behavior where _get_reference_schema_by_id calls would trigger early database flushes, causing IntegrityErrors to be raised before the explicit session.commit() and thus not being caught by the try/except block. Using session.no_autoflush ensures the error handling works as intended.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/better-error-message

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Documentation Link Check Results

❌ Absolute links check failed
There are broken absolute links in the documentation. See workflow logs for details
✅ Relative links check passed
_{Last checked: 2025-09-23 07:16:03 UTC}

[Copilot]

Pull Request Overview

This PR enhances the user experience by providing clearer guidance when a pipeline run name conflict occurs, along with tests and documentation to support the change.

• Enhanced error handling in create_placeholder_run to catch duplicate run-name errors and surface a helpful, actionable message.
• Added unit tests to verify the new error message and ensure other EntityExistsError cases remain unchanged.
• Updated docs to warn about run-name uniqueness and suggest best practices.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/zenml/pipelines/run_utils.py	Improved duplicate run-name error detection and messaging
tests/unit/pipelines/test_run_utils.py	Added tests for duplicate run-name error and non-duplicate behavior
docs/book/how-to/steps-pipelines/yaml_configuration.md	Warn about unique run names and provide guidance in YAML examples
run_alerter_tests.sh	New script to run alerter tests (scope seems unrelated)

Comments suppressed due to low confidence (1)

run_alerter_tests.sh:1

• [nitpick] This script for running alerter tests appears unrelated to the pipeline run-name improvements. Consider moving it to a separate PR or isolating it under a more relevant feature grouping to keep this change focused.

#!/bin/bash

[schustmi]

• This should be handled in the SQLZenStore, not in this random place (which is only one occurence where a run is created).
• Specifying the run name in a config file is not the only one way to do it, the message can simply be generic and talk about configuration instead of files.

[Copilot]

Pull Request Overview

This PR improves the error messaging for duplicate pipeline run names by handling IntegrityError exceptions in SQLZenStore and updating integration tests and documentation to demonstrate the enhanced behavior.

• Enhanced error handling in SQLZenStore to catch duplicate run names and present a user-friendly message
• Fixed the SQLAlchemy autoflush issue to ensure errors are raised at the correct time
• Updated integration tests and docs to reflect and validate the changes made

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
tests/integration/functional/pipelines/test_pipeline_run.py	Added an integration test to verify improved error handling for duplicate pipeline run names
src/zenml/zen_stores/sql_zen_store.py	Enhanced error message handling for duplicate run names and fixed the autoflush issue with session.no_autoflush
src/zenml/pipelines/run_utils.py	Minor update (additional newline)
docs/book/how-to/steps-pipelines/yaml_configuration.md	Added a warning hint to document the uniqueness requirement for run names and provide best practices

[schustmi]

Accidentally approved, see my latest comment