fix(IncrementingCountCursor): Raise a better error when users attempt to use IncrementingCountCursor with partition router

[brianjlai]

We've had a fe different customers write in with issues related to using the IncrementingCountCursor and partition routing at the same time which is not currently supported.

The old error was not very helpful mainly saying: Expected manifest component of type DatetimeBasedCursor, but received IncrementingCountCursor instead which is only really useful if you can reverse engineering our component parsing.

Note: At the moment, this will still not be super useful for the connector builder since all errors get surfaced as Internal Server Error: Server error : 500 Internal Server Error Internal Server Error. But once we fix that builder bug, then this will properly flag and hopefully at least give more info on next steps

Summary by CodeRabbit

• New Features
  • Improved configuration validation: unsupported combinations of incremental count-based cursors with multi-partition routing now fail fast with a clear error message.
• Bug Fixes
  • Prevents proceeding with incompatible sync configurations, reducing confusing runtime behavior and improving reliability.
• Tests
  • Added unit tests to ensure errors are raised for invalid cursor and partitioning combinations.

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Testing This CDK Version

You can test this version of the CDK using the following:

# Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@brian/incrementing_count_cursor_with_partition_router_error_message#egg=airbyte-python-cdk[dev]' --help

# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch brian/incrementing_count_cursor_with_partition_router_error_message

Helpful Resources

• CDK API Reference

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /autofix - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test - Runs connector tests with the updated CDK
• /poe build - Regenerate git-committed build artifacts, such as the pydantic models which are generated from the manifest JSON schema in YAML.
• /poe <command> - Runs any poe command in the CDK environment

📝 Edit this welcome message.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a validation in _build_concurrent_cursor to raise a ValueError when an IncrementingCountCursorModel is used with a non-single PartitionRouter. Updates unit tests to assert the error is raised when combining IncrementingCountCursor with ListPartitionRouter, with a duplicated test present.

Changes

Cohort / File(s)	Summary
Parser guard for unsupported combination airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py	Introduces a check in _build_concurrent_cursor: if model.incremental_sync is IncrementingCountCursorModel and a non-SinglePartitionRouter is configured, raise ValueError instead of building a concurrent cursor.
Unit tests for new error path unit_tests/sources/declarative/parsers/test_model_to_component_factory.py	Adds tests asserting ValueError when IncrementingCountCursor is combined with ListPartitionRouter; includes a duplicated test definition covering the same scenario.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant SM as StreamModel
  participant F as ModelToComponentFactory
  participant PR as PartitionRouter
  participant CC as ConcurrentCursor

  SM->>F: create_component(model)
  F->>PR: resolve_partition_router(model)
  Note over F,PR: New guard check
  alt IncrementingCountCursorModel + non-single PR
    F-->>SM: raise ValueError("Unsupported combination")
  else Other combinations
    F->>CC: build concurrent cursor
    CC-->>F: cursor instance
    F-->>SM: component instance
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat: add IncrementingCountCursor #346: Adds IncrementingCountCursor support and concurrent cursor creation in model_to_component_factory; current PR adds a guard restricting its use with non-single partition routers.
• feat: support state migrations that affects parent streams #770: Restructures state-migration and stream_state flow in _build_concurrent_cursor; current PR modifies the same control path with a new validation.
• fix(concurrent cdk): Properly call set_initial_state() on the cursor that is initialized on the ClientSideIncrementalRecordFilterDecorator #310: Adjusts cursor initialization/state handling; current PR adds a complementary guard impacting cursor construction.

Suggested reviewers

• maxi297

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly and accurately summarizes the primary change, which is raising a clearer error when using IncrementingCountCursor with a partition router, and it focuses on the main fix without extraneous details.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch brian/incrementing_count_cursor_with_partition_router_error_message

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

unit_tests/sources/declarative/parsers/test_model_to_component_factory.py (1)

3672-3722: Consider verifying the error message content, wdyt?

Since the PR's main objective is to provide a clearer error message when users attempt to use IncrementingCountCursor with a partition router, it would be valuable to assert the actual error message in this test. Currently, the test only verifies that a ValueError is raised, but doesn't check that it contains the expected helpful message.

You could enhance the test like this:

-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError) as exc_info:
         factory.create_component(
             model_type=DeclarativeStreamModel,
             component_definition=YamlDeclarativeSource._parse(content),
             config=input_config,
         )
+    assert "PartitionRouter and an IncrementingCountCursor" in str(exc_info.value)
+    assert "test" in str(exc_info.value)  # stream name should be in the message

This way, future changes won't accidentally break the improved error messaging without the test catching it.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c67570b and ee87f0a.

📒 Files selected for processing (2)

• airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py (1 hunks)
• unit_tests/sources/declarative/parsers/test_model_to_component_factory.py (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

unit_tests/sources/declarative/parsers/test_model_to_component_factory.py (1)

airbyte_cdk/sources/declarative/parsers/model_to_component_factory.py (2)

• ModelToComponentFactory (648-4185)
• create_component (789-822)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)

• GitHub Check: Check: source-pokeapi
• GitHub Check: Check: source-hardcoded-records
• GitHub Check: Check: source-shopify
• GitHub Check: Check: destination-motherduck
• GitHub Check: Check: source-intercom
• GitHub Check: Pytest (All, Python 3.11, Ubuntu)
• GitHub Check: Pytest (All, Python 3.13, Ubuntu)
• GitHub Check: Pytest (All, Python 3.10, Ubuntu)
• GitHub Check: Pytest (All, Python 3.12, Ubuntu)
• GitHub Check: Pytest (Fast)
• GitHub Check: SDM Docker Image Build
• GitHub Check: Manifest Server Docker Image Build

[github-actions]

PyTest Results (Fast)

3 780 tests  +1   3 768 ✅ +1   6m 25s ⏱️ -3s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit ee87f0a. ± Comparison against base commit c67570b.

[github-actions]

PyTest Results (Full)

3 783 tests  +1   3 771 ✅ +1   11m 3s ⏱️ +9s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit ee87f0a. ± Comparison against base commit c67570b.

[maxi297]

LGTM!