0
# Exceptions
1

2
Exception classes for error handling in ZenML. All ZenML exceptions inherit from `ZenMLBaseException` for consistent error handling and categorization.
3

4
## Capabilities
5

6
### Base Exception
7

8
```python { .api }
9
class ZenMLBaseException(Exception):
10
    """
11
    Base exception for all ZenML exceptions.
12

13
    All custom ZenML exceptions inherit from this class,
14
    making it easy to catch any ZenML-specific error.
15

16
    Example:
17
    ```python
18
    try:
19
        # ZenML operations
20
        pass
21
    except ZenMLBaseException as e:
22
        print(f"ZenML error: {e}")
23
    ```
24
    """
25
```
26

27
Import from:
28

29
```python
30
from zenml.exceptions import ZenMLBaseException
31
```
32

33
### Authorization and Authentication
34

35
```python { .api }
36
class AuthorizationException(ZenMLBaseException):
37
    """
38
    Authorization/access errors.
39

40
    Raised when user lacks permissions for an operation.
41
    """
42

43
class CredentialsNotValid(AuthorizationException):
44
    """
45
    Invalid credentials error.
46

47
    Raised when credentials are invalid or expired.
48
    Triggers re-authentication flow.
49
    """
50

51
class OAuthError(ZenMLBaseException):
52
    """
53
    OAuth2 authentication errors.
54

55
    Raised during OAuth2 authentication flows.
56
    """
57
```
58

59
Import from:
60

61
```python
62
from zenml.exceptions import (
63
    AuthorizationException,
64
    CredentialsNotValid,
65
    OAuthError
66
)
67
```
68

69
### Entity Operations
70

71
```python { .api }
72
class DoesNotExistException(ZenMLBaseException):
73
    """
74
    Entity not found errors.
75

76
    Raised when attempting to access a non-existent resource.
77
    """
78

79
class EntityExistsError(ZenMLBaseException):
80
    """
81
    Entity already exists errors.
82

83
    Raised when attempting to create a resource that already exists.
84
    """
85

86
class EntityCreationError(ZenMLBaseException):
87
    """
88
    Entity creation failures.
89

90
    Raised when entity creation fails due to validation or constraints.
91
    """
92
```
93

94
Import from:
95

96
```python
97
from zenml.exceptions import (
98
    DoesNotExistException,
99
    EntityExistsError,
100
    EntityCreationError
101
)
102
```
103

104
### Step and Pipeline Errors
105

106
```python { .api }
107
class StepInterfaceError(ZenMLBaseException):
108
    """
109
    Step interface usage errors.
110

111
    Raised when step decorators or interfaces are used incorrectly.
112
    """
113

114
class StepContextError(ZenMLBaseException):
115
    """
116
    Step context access errors.
117

118
    Raised when attempting to access step context outside execution.
119
    """
120

121
class InputResolutionError(ZenMLBaseException):
122
    """
123
    Step input resolution failures.
124

125
    Raised when step inputs cannot be resolved or connected.
126
    """
127

128
class RunStoppedException(ZenMLBaseException):
129
    """
130
    Pipeline run stopped by user.
131

132
    Raised when a pipeline run is explicitly stopped.
133
    """
134

135
class RunInterruptedException(ZenMLBaseException):
136
    """
137
    Step run interrupted.
138

139
    Raised when step execution is interrupted.
140
    """
141
```
142

143
Import from:
144

145
```python
146
from zenml.exceptions import (
147
    StepInterfaceError,
148
    StepContextError,
149
    InputResolutionError,
150
    RunStoppedException,
151
    RunInterruptedException
152
)
153
```
154

155
### Stack and Component Errors
156

157
```python { .api }
158
class StackComponentInterfaceError(ZenMLBaseException):
159
    """
160
    Stack component interface errors.
161

162
    Raised when stack component interfaces are used incorrectly.
163
    """
164

165
class StackValidationError(ZenMLBaseException):
166
    """
167
    Stack configuration validation errors.
168

169
    Raised when stack configuration is invalid or incompatible.
170
    """
171

172
class ArtifactStoreInterfaceError(ZenMLBaseException):
173
    """
174
    Artifact store interface errors.
175

176
    Raised when artifact store operations fail.
177
    """
178
```
179

180
Import from:
181

182
```python
183
from zenml.exceptions import (
184
    StackComponentInterfaceError,
185
    StackValidationError,
186
    ArtifactStoreInterfaceError
187
)
188
```
189

190
### Materializer Errors
191

192
```python { .api }
193
class MaterializerInterfaceError(ZenMLBaseException):
194
    """
195
    Materializer interface errors.
196

197
    Raised when materializer operations fail or are used incorrectly.
198
    """
199
```
200

201
Import from:
202

203
```python
204
from zenml.exceptions import MaterializerInterfaceError
205
```
206

207
### Integration Errors
208

209
```python { .api }
210
class IntegrationError(ZenMLBaseException):
211
    """
212
    Integration activation errors.
213

214
    Raised when integration requirements are not met or activation fails.
215
    """
216

217
class CustomFlavorImportError(ZenMLBaseException):
218
    """
219
    Custom flavor import failures.
220

221
    Raised when custom flavor cannot be imported.
222
    """
223
```
224

225
Import from:
226

227
```python
228
from zenml.exceptions import IntegrationError, CustomFlavorImportError
229
```
230

231
### Validation Errors
232

233
```python { .api }
234
class ValidationError(ZenMLBaseException):
235
    """
236
    Model/data validation errors.
237

238
    Raised when Pydantic model validation fails or data is invalid.
239
    """
240

241
class HydrationError(ZenMLBaseException):
242
    """
243
    Model hydration failures.
244

245
    Raised when model objects cannot be hydrated from stored data.
246
    """
247

248
class HookValidationException(ZenMLBaseException):
249
    """
250
    Hook validation failures.
251

252
    Raised when hook specifications are invalid.
253
    """
254
```
255

256
Import from:
257

258
```python
259
from zenml.exceptions import (
260
    ValidationError,
261
    HydrationError,
262
    HookValidationException
263
)
264
```
265

266
### Settings and Configuration Errors
267

268
```python { .api }
269
class SettingsResolvingError(ZenMLBaseException):
270
    """
271
    Settings resolution failures.
272

273
    Raised when step or pipeline settings cannot be resolved.
274
    """
275

276
class SecretsStoreNotConfiguredError(ZenMLBaseException):
277
    """
278
    Secrets store not configured.
279

280
    Raised when secrets operations attempted without configured store.
281
    """
282

283
class BackupSecretsStoreNotConfiguredError(ZenMLBaseException):
284
    """
285
    Backup secrets store not configured.
286

287
    Raised when backup secrets operations attempted without configured store.
288
    """
289
```
290

291
Import from:
292

293
```python
294
from zenml.exceptions import (
295
    SettingsResolvingError,
296
    SecretsStoreNotConfiguredError,
297
    BackupSecretsStoreNotConfiguredError
298
)
299
```
300

301
### Operation Errors
302

303
```python { .api }
304
class IllegalOperationError(ZenMLBaseException):
305
    """
306
    Illegal operation attempts.
307

308
    Raised when attempting operations that are not allowed in current context.
309
    """
310

311
class MethodNotAllowedError(ZenMLBaseException):
312
    """
313
    HTTP method not allowed.
314

315
    Raised for REST API method errors.
316
    """
317

318
class MaxConcurrentTasksError(ZenMLBaseException):
319
    """
320
    Concurrent task limit reached.
321

322
    Raised when maximum concurrent tasks limit is exceeded.
323
    """
324

325
class WebhookInactiveError(ZenMLBaseException):
326
    """
327
    Inactive webhook errors.
328

329
    Raised when attempting to use inactive webhook.
330
    """
331
```
332

333
Import from:
334

335
```python
336
from zenml.exceptions import (
337
    IllegalOperationError,
338
    MethodNotAllowedError,
339
    MaxConcurrentTasksError,
340
    WebhookInactiveError
341
)
342
```
343

344
### System Errors
345

346
```python { .api }
347
class InitializationException(ZenMLBaseException):
348
    """
349
    Repository initialization errors.
350

351
    Raised when ZenML repository initialization fails.
352
    """
353

354
class GitNotFoundError(ZenMLBaseException):
355
    """
356
    Git not installed errors.
357

358
    Raised when Git is required but not found on system.
359
    """
360

361
class SubscriptionUpgradeRequiredError(ZenMLBaseException):
362
    """
363
    Subscription tier limitation.
364

365
    Raised when feature requires higher subscription tier.
366
    """
367

368
class RunMonitoringError(ZenMLBaseException):
369
    """
370
    Pipeline run monitoring errors.
371

372
    Raised when run monitoring operations fail.
373
    """
374

375
class HookExecutionException(ZenMLBaseException):
376
    """
377
    Hook execution failures.
378

379
    Raised when hook execution fails during pipeline/step execution.
380
    """
381
```
382

383
Import from:
384

385
```python
386
from zenml.exceptions import (
387
    InitializationException,
388
    GitNotFoundError,
389
    SubscriptionUpgradeRequiredError,
390
    RunMonitoringError,
391
    HookExecutionException
392
)
393
```
394

395
### Custom Exception
396

397
```python { .api }
398
class ZenKeyError(KeyError, ZenMLBaseException):
399
    """
400
    KeyError with multiline message support.
401

402
    Enhanced KeyError that supports detailed error messages.
403
    """
404
```
405

406
Import from:
407

408
```python
409
from zenml.exceptions import ZenKeyError
410
```
411

412
## Usage Examples
413

414
### Catching ZenML Errors
415

416
```python
417
from zenml.client import Client
418
from zenml.exceptions import ZenMLBaseException, DoesNotExistException
419

420
client = Client()
421

422
try:
423
    pipeline = client.get_pipeline("nonexistent_pipeline")
424
except DoesNotExistException as e:
425
    print(f"Pipeline not found: {e}")
426
except ZenMLBaseException as e:
427
    print(f"ZenML error: {e}")
428
```
429

430
### Handling Authentication Errors
431

432
```python
433
from zenml.client import Client
434
from zenml.exceptions import AuthorizationException, CredentialsNotValid
435

436
try:
437
    client = Client()
438
    # Perform authenticated operation
439
    client.list_pipelines()
440
except CredentialsNotValid:
441
    print("Credentials expired. Please re-authenticate.")
442
    # Trigger re-authentication
443
except AuthorizationException as e:
444
    print(f"Not authorized: {e}")
445
```
446

447
### Handling Entity Creation
448

449
```python
450
from zenml.client import Client
451
from zenml.exceptions import EntityExistsError, EntityCreationError
452

453
client = Client()
454

455
try:
456
    stack = client.create_stack(
457
        name="my_stack",
458
        components={"orchestrator": "local", "artifact_store": "local"}
459
    )
460
except EntityExistsError:
461
    print("Stack already exists")
462
    stack = client.get_stack("my_stack")
463
except EntityCreationError as e:
464
    print(f"Failed to create stack: {e}")
465
```
466

467
### Step Context Errors
468

469
```python
470
from zenml import get_step_context
471
from zenml.exceptions import StepContextError
472

473
try:
474
    context = get_step_context()
475
    print(context.step_name)
476
except StepContextError:
477
    print("Not inside step execution")
478
```
479

480
### Stack Validation
481

482
```python
483
from zenml.client import Client
484
from zenml.exceptions import StackValidationError
485

486
client = Client()
487

488
try:
489
    client.create_stack(
490
        name="invalid_stack",
491
        components={}  # Missing required components
492
    )
493
except StackValidationError as e:
494
    print(f"Stack validation failed: {e}")
495
```
496

497
### Integration Errors
498

499
```python
500
from zenml.integrations.aws import AWSIntegration
501
from zenml.exceptions import IntegrationError
502

503
try:
504
    if not AWSIntegration.check_installation():
505
        raise IntegrationError("AWS integration not installed")
506
except IntegrationError as e:
507
    print(f"Integration error: {e}")
508
    print("Install with: pip install zenml[aws]")
509
```
510

511
### Hook Execution
512

513
```python
514
from zenml import pipeline
515
from zenml.exceptions import HookExecutionException
516

517
def my_hook():
518
    raise ValueError("Hook failed")
519

520
@pipeline(on_success=my_hook)
521
def my_pipeline():
522
    pass
523

524
try:
525
    my_pipeline()
526
except HookExecutionException as e:
527
    print(f"Hook execution failed: {e}")
528
```
529

530
### Comprehensive Error Handling
531

532
```python
533
from zenml import pipeline, step
534
from zenml.exceptions import (
535
    ZenMLBaseException,
536
    StepInterfaceError,
537
    InputResolutionError,
538
    RunStoppedException,
539
    StackValidationError
540
)
541

542
@step
543
def risky_step(data: list) -> dict:
544
    if not data:
545
        raise ValueError("Empty data")
546
    return {"processed": data}
547

548
@pipeline
549
def error_handling_pipeline():
550
    try:
551
        data = []
552
        result = risky_step(data)
553
    except StepInterfaceError as e:
554
        print(f"Step interface error: {e}")
555
    except InputResolutionError as e:
556
        print(f"Input resolution error: {e}")
557
    except ZenMLBaseException as e:
558
        print(f"ZenML error: {e}")
559
    except Exception as e:
560
        print(f"Unexpected error: {e}")
561
```
562

563
### Custom Exception Context
564

565
```python
566
from zenml.exceptions import ZenMLBaseException
567

568
class CustomPipelineError(ZenMLBaseException):
569
    """Custom exception for pipeline-specific errors."""
570
    pass
571

572
def validate_data(data):
573
    if not isinstance(data, list):
574
        raise CustomPipelineError(
575
            f"Expected list, got {type(data).__name__}"
576
        )
577

578
try:
579
    validate_data("not a list")
580
except CustomPipelineError as e:
581
    print(f"Validation error: {e}")
582
```
583