livecycle
Fix misleading error messages when Kubernetes configuration is missing
Problem
Users running GitHub Actions workflows with Preevy's Kubernetes driver were getting misleading error messages that suggested tunnel server connectivity issues when the actual problem was missing or incorrect Kubernetes configuration. This made troubleshooting difficult, especially in CI/CD environments where users couldn't easily distinguish between tunnel server problems and Kubernetes cluster connectivity issues.
Solution
Enhanced the Kubernetes driver's error handling to detect common connectivity issues and provide clear, actionable error messages that explicitly identify them as Kubernetes-related problems.
Key Changes
Added KubernetesConnectionError class for Kubernetes-specific errors with enhanced messaging.
Improved error detection in the logError wrapper to identify and enhance:
- Connection refused errors (ECONNREFUSED) → Cluster unreachable
- DNS resolution failures (ENOTFOUND) → Hostname resolution issues
- Authentication errors (401) → Credential problems
- Authorization errors (403) → Permission issues
- Timeout errors → Network connectivity problems
- Configuration errors → Missing/invalid kubeconfig
Enhanced error messages that provide specific guidance and explicitly state:
"This is a Kubernetes connectivity issue, not a tunnel server problem."
Example
Before:
Cannot connect to ssh://tunnel.example.com:2222: connect ECONNREFUSED 10.0.0.1:6443
After:
Failed to connect to Kubernetes cluster. The Kubernetes API server appears to be unreachable.
Please check that your cluster is running and accessible.
This is a Kubernetes connectivity issue, not a tunnel server problem.
Testing
- Added comprehensive unit and integration tests (30 total tests)
- All existing functionality preserved - non-connection errors pass through unchanged
- Verified error enhancement works for various failure scenarios
- Created demo script showing before/after error messages
Impact
- Improves user experience in GitHub Actions and CI environments
- Reduces confusion between tunnel server and Kubernetes issues
- Provides actionable guidance for troubleshooting cluster connectivity
- Maintains backward compatibility with existing error handling
Fixes the issue where users received misleading tunnel server error messages when Kubernetes configuration was missing or incorrect.
Original prompt
This section details on the original issue you should resolve
<issue_title>[Bug]: Bad kubernetes configuration causes misleading error</issue_title> <issue_description>### What happened?
My GitHub Actions workflow was missing the k8s config, but the error made it look like something was wrong with the tunnel server.
Add screenshots
Steps to reproduce the behavior
Set up a GHA workflow with a preevy profile using kubernetes, but don't add any configuration for the kubernetes client.
Expected behavior
Expected an error that indicated a connection problem with kubernetes rather than with the tunnel server.
What OS are you seeing the problem on?
No response
Additional context
No response
Record
- [X] I agree to follow this project's Code of Conduct</issue_description>
Comments on the Issue (you are @copilot in this section)
💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.
