fix(cloud): return actionable errors when creating a connection fails by calebevans-ab · Pull Request #1347 · airbytehq/PyAirbyte

Caleb Evans (calebevans-ab) · 2026-10-08T16:48:23Z

TL;DR

create_connection_on_cloud / CloudWorkspace.deploy_connection now return readable PyAirbyte errors instead of a raw SDKError when a create fails. A bad stream name keeps the API's own message. A bad or swapped source_id / destination_id is caught before the create, and the error names the argument. No other tool changes.

Summary

Resolves AGENTIC-2336.

When a create fails, create_connection_on_cloud (and CloudWorkspace.deploy_connection underneath it) leaked a raw airbyte_api SDKError. The cause: api_util.create_connection was one of the few API wrappers without except SDKError. Agents got API error occurred: Status 400 plus a JSON blob, or a bare 403 Forbidden, and neither said which argument was wrong.

api_util.create_connection

except SDKError as e:
    if e.status_code == 400:
        # message = body["data"]["message"] -> body["detail"] -> generic fallback
        raise AirbyteLibInputError(message=..., guidance="Check `selected_streams` ...") from e
    raise _wrap_sdk_error(e, {source_id, destination_id, selected_stream_names}) from e

A 400 goes to AirbyteLibInputError on purpose. Plain _wrap_sdk_error would turn it into AirbyteCloudError("API error occurred: API error occurred") and drop the response body, which holds the useful line ("No streams found with name [...]"). _wrap_sdk_error itself is unchanged.

create_connection_on_cloud

Before deploying, it fetches the source and destination through the existing wrapped api_util.get_source / get_destination. A not-found result is re-raised as AirbyteMissingResourceError naming `source_id` or `destination_id`.
Previously the source was looked up only when selected_streams was omitted, and the destination never was. A bad or swapped ID with explicit streams therefore reached the create call and leaked a raw 403.
This costs two extra GETs per create.
_get_suggested_streams_for_source now takes the already-fetched CloudSource, so the source isn't fetched twice.

No other tool and no shared error handling changes. Library callers of deploy_connection now get PyAirbyte error types instead of SDKError when a create fails.

Agent-visible text after the change, from the live sandbox:

Bad stream: No streams found with name [no_such_stream_xyz] and namespace [null]. Please call the .../getstreamproperties endpoint ... Check that every name in selected_streamsis a stream of the source, and thatsource_idanddestination_id are correct.
Bad destination: `destination_id` '<id>' was not found in workspace '<ws>', or these credentials can't access it. Airbyte Cloud returns 403 both for IDs that don't exist and for resources outside your access. ...

Note: #1148 (replacing the Speakeasy SDK) touches the same SDKError handling. If it lands first, this needs rebasing.

Testing

uv run poe check and ruff format --check pass. tests/unit_tests/test_cloud_api_util.py and tests/unit_tests/test_mcp_cloud.py: 243 passed. New tests cover 400 with the API body, 400 with a non-JSON body, 403/500 wrapping, and an unknown source or destination naming the argument.
Live, through the MCP tool against the sandbox workspace: bad stream, nonexistent destination, nonexistent source with explicit streams, and destination ID passed as source_id all return the new text. A valid create still succeeded; the throwaway connection was deleted afterwards.

Link to Devin session: https://app.devin.ai/sessions/6e92865abf9b4b638db4447c362787d6
Open in Devin Desktop: https://app.devin.ai/desktop/session/6e92865abf9b4b638db4447c362787d6?variant=devin
Requested by: Caleb Evans (@calebevans-ab)

Important

Auto-merge enabled.

This PR is set to merge automatically when all requirements are met.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration · 2026-10-08T16:48:27Z

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

Disable automatic comment, CI, and merge conflict monitoring

linear-code · 2026-10-08T16:48:30Z

AGENTIC-2336

github-actions · 2026-10-08T16:48:45Z

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This PyAirbyte Version

You can test this version of PyAirbyte using the following:

# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1791477590-create-connection-errors' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1791477590-create-connection-errors'

PR Slash Commands

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

/fix-pr - Fixes most formatting and linting issues
/uv-lock - Updates uv.lock file
/test-pr - Runs tests with the updated PyAirbyte
/prerelease - Builds and publishes a prerelease version to PyPI

📚 Show Repo Guidance

Helpful Resources

Community Support

Questions? Join the #pyairbyte channel in our Slack workspace.

📝 Edit this welcome message.

…/1791477590-create-connection-errors

chatgpt-codex-connector · 2026-10-08T16:50:31Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T16:55:23.752089Z	`5b6bc28`	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "Codex (@codex) review" or "Codex (@codex) security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Caleb Evans (calebevans-ab) · 2026-10-08T16:53:33Z

Codex (@codex) review

chatgpt-codex-connector · 2026-10-08T16:55:22Z

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 5b6bc28236

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".

github-code-quality · 2026-10-08T16:56:09Z

Code Coverage Overview

Languages: Python

Python / code-coverage/pytest-no-creds

The overall line coverage in commit 4f699d6 in the devin/1791477590-cre... branch is 78%. The line coverage in commit d9f652f in the release-candidate/v1 branch is 65%.

Show a line coverage summary of the most impacted files.

File	`release-candidate/v1` d9f652f	`devin/1791477590-cre...` 4f699d6	+/-
`airbyte/_util/api_util.py`	36%	66%	+30%
`airbyte/mcp/cloud.py`	52%	83%	+31%
`airbyte/cloud/connectors.py`	34%	75%	+41%
`airbyte/mcp/int..._registry_ui.py`	0%	92%	+92%
`airbyte/mcp/_user_identity.py`	0%	93%	+93%
`airbyte/_direct...ctors/models.py`	0%	94%	+94%
`airbyte/mcp/_telemetry.py`	0%	94%	+94%
`airbyte/mcp/_sso_auth.py`	0%	96%	+96%
`airbyte/cloud/models.py`	0%	97%	+97%
`airbyte/mcp/int...nc_status_ui.py`	0%	97%	+97%

Python / code-coverage/pytest-unit

The overall line coverage in commit 4f699d6 in the devin/1791477590-cre... branch is 74%. Line coverage data for the release-candidate/v1 branch is not yet available.

Show a line coverage summary of the most covered files.

File	`release-candidate/v1`	`devin/1791477590-cre...` 4f699d6	+/-
`airbyte/cloud/models.py`	—	97%	—
`airbyte/mcp/_sso_auth.py`	—	96%	—
`airbyte/_direct...ctors/models.py`	—	94%	—
`airbyte/cloud/client.py`	—	90%	—
`airbyte/exceptions.py`	—	85%	—
`airbyte/mcp/cloud.py`	—	83%	—
`airbyte/progress.py`	—	80%	—
`airbyte/cloud/connectors.py`	—	75%	—
`airbyte/shared/...ql_processor.py`	—	68%	—
`airbyte/_util/api_util.py`	—	66%	—

_{Updated October 08, 2026 17:21 UTC}

Aldo Gonzalez (aldogonzalez8)

APPROVED
left annoying comment

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

fix(cloud): return actionable errors when creating a connection fails

73a9264

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration Bot assigned Caleb Evans (calebevans-ab) Oct 8, 2026

Merge remote-tracking branch 'origin/release-candidate/v1' into devin…

5b6bc28

…/1791477590-create-connection-errors

Caleb Evans (calebevans-ab) marked this pull request as ready for review October 8, 2026 16:50

Aldo Gonzalez (aldogonzalez8) approved these changes Oct 8, 2026

View reviewed changes

Comment thread airbyte/_util/api_util.py Outdated

refactor(cloud): simplify SDK error detail parsing in create_connection

4f699d6

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Caleb Evans (calebevans-ab) enabled auto-merge (squash) October 8, 2026 17:12

Caleb Evans (calebevans-ab) merged commit 29ba033 into release-candidate/v1 Oct 8, 2026
28 checks passed

Caleb Evans (calebevans-ab) deleted the devin/1791477590-create-connection-errors branch October 8, 2026 17:22

Navigation Menu

Repository navigation

fix(cloud): return actionable errors when creating a connection fails - #1347

fix(cloud): return actionable errors when creating a connection fails#1347
Caleb Evans (calebevans-ab) merged 3 commits into
release-candidate/v1from
devin/1791477590-create-connection-errors

Caleb Evans (calebevans-ab) commented Oct 8, 2026 •

edited by github-actions Bot

Loading

Uh oh!

devin-ai-integration Bot commented Oct 8, 2026

Uh oh!

linear-code Bot commented Oct 8, 2026

Uh oh!

github-actions Bot commented Oct 8, 2026

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

Caleb Evans (calebevans-ab) commented Oct 8, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026

Uh oh!

github-code-quality Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

Aldo Gonzalez (aldogonzalez8) left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Caleb Evans (calebevans-ab) commented Oct 8, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

Summary

Testing

Uh oh!

devin-ai-integration Bot commented Oct 8, 2026

Uh oh!

linear-code Bot commented Oct 8, 2026

Uh oh!

github-actions Bot commented Oct 8, 2026

👋 Greetings, Airbyte Team Member!

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Review Summary

Uh oh!

Caleb Evans (calebevans-ab) commented Oct 8, 2026

Uh oh!

chatgpt-codex-connector Bot commented Oct 8, 2026

Uh oh!

github-code-quality Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Overview

Python / code-coverage/pytest-no-creds

Python / code-coverage/pytest-unit

Uh oh!

Aldo Gonzalez (aldogonzalez8) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Caleb Evans (calebevans-ab) commented Oct 8, 2026 •

edited by github-actions Bot

Loading

chatgpt-codex-connector Bot commented Oct 8, 2026 •

edited

Loading

github-code-quality Bot commented Oct 8, 2026 •

edited

Loading