kubeflow / kubeflow/sdk

Define shared exception hierarchy across Kubeflow SDK clients

Open
#458 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
148
Forks
262
Avg merge
1d 2h
Merged PRs (30d)
1

Description

### What

Today, Kubeflow SDK clients (`TrainerClient`, `ModelRegistryClient`, and the upcoming `PipelinesClient`) raise generic Python exceptions (`ValueError`, `RuntimeError`, `TimeoutError`) for domain-specific errors like name resolution failures, compilation errors, and run failures. This makes it difficult for users to catch and handle errors precisely without accidentally catching unrelated exceptions.

### How

Define a shared exception hierarchy in `kubeflow.common.exceptions` (or similar) that all SDK clients adopt. Proposed starting set:

| Exception | Use case |
|---|---|
| `KubeflowError` | Base class for all Kubeflow SDK errors |
| `NameResolutionError(KubeflowError)` | Resource not found by name (pipeline, experiment, job, model, etc.) |
| `CompilationError(KubeflowError)` | Pipeline or job spec failed to compile |
| `RunFailedError(KubeflowError)` | A run/job reached a failed state during a wait operation |
| `KubeflowTimeoutError(KubeflowError)` | A wait operation exceeded its timeout |

The hierarchy should be minimal and extensible — clients can subclass further if needed (e.g. `PipelineNotFoundError(NameResolutionError)`), but the common set covers the majority of cases.

### Acceptance

- [ ] Shared exception module exists in the SDK (e.g. `kubeflow.common.exceptions`)
- [ ] At least one existing client (`TrainerClient` or `ModelRegistryClient`) migrates to the new exceptions
- [ ] `PipelinesClient` (KEP-125) adopts the shared exceptions from the start
- [ ] Exceptions are documented with when each is raised

### Context

Raised during review of [KEP-125: PipelinesClient](https://github.com/kubeflow/sdk/pull/343) — the error handling table uses generic exceptions, and reviewers suggested custom exceptions that are shared across all SDK clients.

Contributor guide

Open the contributing guide

Research direction

Start with the proposed shared module at kubeflow.common.exceptions and inspect how TrainerClient and ModelRegistryClient currently raise generic exceptions. Review the KEP-125 PipelinesClient error-handling table, then trace the affected client operations. Done means the shared hierarchy is documented, at least one existing client and PipelinesClient use it, and the listed domain-specific cases are covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.