[devin-ai-integration]

Summary

When a file-based connector's connection check fails, the platform was rendering the full Python traceback as the user-facing error message. Patrick reported this for the Google Drive Agent Connector — both "service account key in the wrong format" and "no files match the default glob" surfaced as raw stack traces in the Engine UI popup instead of an actionable message.

Two issues in default_file_based_availability_strategy.py are responsible for this across all file-based connectors (S3, GCS, Azure, SFTP, Google Drive, ...):

1. _check_list_files's broad except Exception was swallowing AirbyteTracedExceptions raised by stream readers. For example, source-google-drive's _build_google_service already raises a perfect AirbyteTracedException(failure_type=config_error, message="Could not authenticate with Google drive. Please check your credentials."), but it got re-wrapped as a generic CheckAvailabilityError(ERROR_LISTING_FILES, ...), losing the actionable text.
2. check_availability and check_availability_and_parsability returned "".join(traceback.format_exc()) as the failure reason. FileBasedSource.check_connection then propagated that traceback string verbatim into AirbyteTracedException.message, which the platform exposes as external_message and the Engine renders in the popup.

This PR:

• Re-raises AirbyteTracedException from _check_list_files so connector-specific actionable messages propagate unchanged to the platform.
• Returns str(exc) from the two CheckAvailability* methods instead of the full traceback. The actionable message comes from BaseFileBasedSourceError's string representation, which already includes the FileBasedSourceError enum text (e.g. the EMPTY_STREAM sentence). The full traceback is still emitted to the connector log via logger.exception(...) for debugging.

User-visible result for the two reported cases (no behavior change for the happy path):

• Bad service account key: popup becomes Unable to connect to stream files - Could not authenticate with Google drive. Please check your credentials.
• No files match glob: popup becomes No files were identified in the stream. This may be because there are no files in the specified container, or because your glob patterns did not match any files. Please verify that your source contains files last modified after the start_date and that your glob patterns are not overly strict. Contact Support if you need assistance. stream=files

Both strings already exist and comply with the error-message guidelines — they were just buried in tracebacks.

Review & Testing Checklist for Human

• Confirm there are no callers depending on the reason string starting with Traceback ... (a quick grep across airbytehq/airbyte connectors and airbytehq/airbyte-platform-internal for substrings like "Traceback (most recent call last)" against the file-based check reason should show no positive consumers).
• Spot-check one or two non-Google-Drive file-based connectors (e.g. source-s3, source-sftp) by triggering a check failure and verifying the popup shows the actionable string rather than a stack trace.
• Verify logger.exception("Stream availability check failed") produces the expected log entry in connector stdout — the full traceback should still be in the logs for debugging.

Notes

• New unit tests in test_default_file_based_availability_strategy.py cover both fixes:
  • test_not_available_given_no_files / test_check_availability_returns_actionable_reason_when_no_files assert the reason contains the actionable enum text and does not contain Traceback or raise CheckAvailabilityError.
  • test_airbyte_traced_exception_from_stream_reader_propagates / test_airbyte_traced_exception_propagates_in_check_availability assert that AirbyteTracedExceptions raised by the stream reader propagate unchanged with their original message and failure_type.
• Local run: poetry run pytest unit_tests/sources/file_based/ -x -q passes.
• Reported by Patrick in the #ask-devin-ai thread (https://airbytehq-team.slack.com/archives/C08BHPUMEPJ/p1777762733898279). A follow-up PR in airbytehq/airbyte could differentiate Google Drive's _build_google_service failure modes (json.JSONDecodeError → "Service Account Key must contain valid JSON" / ValueError from load_pem_private_key → "Service Account Key is not a valid PEM-encoded private key") for an even more specific message — happy to do that as a separate small PR if desired.

Link to Devin session: https://app.devin.ai/sessions/7ddfcdf1232643c48efb777a5bc66e26

Important

Auto-merge enabled.

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

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

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@devin/1777763056-file-based-actionable-error-messages#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 devin/1777763056-file-based-actionable-error-messages

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
• /prerelease - Triggers a prerelease publish with default arguments
• /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

📚 Show Repo Guidance

Helpful Resources

• CDK API Reference

📝 Edit this welcome message.

[Copilot]

Pull request overview

This PR improves file-based connector connection-check UX by ensuring actionable, connector-specific error messages are surfaced to the platform instead of full Python tracebacks, while still logging tracebacks for debugging.

Changes:

• Re-raise AirbyteTracedException from _check_list_files so connector-provided actionable messages and failure_type propagate unchanged.
• Return str(CheckAvailabilityError) (and log via logger.exception) instead of returning traceback.format_exc() as the user-facing failure reason.
• Add unit tests verifying (a) no traceback text is returned in the reason and (b) AirbyteTracedException propagates from both availability-check methods.

Reviewed changes

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

File	Description
airbyte_cdk/sources/file_based/availability_strategy/default_file_based_availability_strategy.py	Stops returning traceback strings as reasons; logs exceptions and preserves actionable error messages; re-raises AirbyteTracedException from file listing.
unit_tests/sources/file_based/availability_strategy/test_default_file_based_availability_strategy.py	Adds regression tests ensuring actionable reasons are returned and AirbyteTracedException is not swallowed/wrapped.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

PyTest Results (Fast)

4 043 tests  +3   4 032 ✅ +3   7m 50s ⏱️ +5s
    1 suites ±0      11 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit bc20506. ± Comparison against base commit 886fcf8.

[github-actions]

PyTest Results (Full)

4 046 tests  +3   4 034 ✅ +3   10m 49s ⏱️ -34s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit bc20506. ± Comparison against base commit 886fcf8.