fix: improve ERROR_READING_FILE message and raise AirbyteTracedException with system_error

[devin-ai-integration]

Summary

Improves the generic ERROR_READING_FILE error in the file-based CDK availability strategy. The previous message ("Error opening file. Please check the credentials provided...") was misleading because file read failures during availability checks are not necessarily credential issues — they can be caused by dependency conflicts, corrupted files, or transient I/O errors.

Changes:

• exceptions.py: Updated ERROR_READING_FILE message from credential-focused text to "File read failed during availability check."
• default_file_based_availability_strategy.py: In _check_parse_record, the catch-all except Exception now raises AirbyteTracedException with FailureType.system_error instead of CheckAvailabilityError. The internal_message preserves the file URI, stream name, and original exception for debugging.

No test changes were required. The AirbyteTracedException raised here is caught upstream by check_connection in file_based_source.py, which wraps it with config_error and returns a graceful connectionStatus: FAILED — so the existing test scenarios continue to expect a returned status object (not a raised exception).

Resolves https://github.com/airbytehq/airbyte-internal-issues/issues/16082
Related to https://github.com/airbytehq/oncall/issues/11723

Review & Testing Checklist for Human

• Verify upstream catch behavior: The new AirbyteTracedException(system_error) propagates out of _check_parse_record and is caught by check_connection in file_based_source.py (lines ~204-230), which wraps it into a new AirbyteTracedException(config_error). The entrypoint then handles config_error gracefully (returns connectionStatus: FAILED). Confirm this is the desired end-to-end behavior — in particular that system_error being re-wrapped as config_error is acceptable.
• Check for other CheckAvailabilityError catch sites: Verify no other code paths catch CheckAvailabilityError specifically and would now miss the AirbyteTracedException.
• Evaluate whether the new message is too terse: "File read failed during availability check." is accurate but gives the user no remediation hint. Consider whether a follow-up sentence is needed.

Recommended test plan: Run the file-based check scenario tests (test_file_based_check[error_reading_file_scenario] and test_file_based_check[error_multi_stream_scenario]) and confirm they pass. CI already passes these.

Notes

• The ERROR_LISTING_FILES enum value still has the old credential-focused message pattern — that's a separate concern and intentionally not changed here.
• Initial test scenario changes (switching set_expected_check_error to expect AirbyteTracedException) were reverted after CI showed the exception is handled internally by check_connection, not raised to the test harness.

Link to Devin session: https://app.devin.ai/sessions/924b76b526934bf59aedb5cbb21d7e43

[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/1774038090-improve-error-reading-file-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 devin/1774038090-improve-error-reading-file-message

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.

[github-actions]

PyTest Results (Fast)

3 934 tests  ±0   3 923 ✅ +1   7m 9s ⏱️ ±0s
    1 suites ±0      11 💤  - 1 
    1 files   ±0       0 ❌ ±0 

Results for commit 6d6ca32. ± Comparison against base commit 0e57414.

♻️ This comment has been updated with latest results.

[github-actions]

PyTest Results (Full)

3 937 tests  ±0   3 925 ✅ ±0   10m 48s ⏱️ -26s
    1 suites ±0      12 💤 ±0 
    1 files   ±0       0 ❌ ±0 

Results for commit 6d6ca32. ± Comparison against base commit 0e57414.

♻️ This comment has been updated with latest results.