0
# Error Handling
1
2
TensorBoard provides a structured exception hierarchy with HTTP-aware error classes designed for web application error handling. These errors automatically format HTTP responses with appropriate status codes and headers when raised in TensorBoard's web interface.
3
4
## Capabilities
5
6
### Base Error Class
7
8
Foundation class for all TensorBoard public-facing errors with HTTP response integration.
9
10
```python { .api }
11
class PublicError(RuntimeError):
12
"""
13
An error whose text does not contain sensitive information.
14
15
Attributes:
16
http_code (int): HTTP status code between 400-599 (default 500)
17
headers (list): Additional HTTP headers as key-value pairs
18
"""
19
20
http_code = 500
21
22
def __init__(self, details):
23
"""
24
Initialize a PublicError.
25
26
Args:
27
details: Error message details
28
"""
29
```
30
31
### Invalid Argument Errors
32
33
HTTP 400 Bad Request errors for client-provided invalid arguments.
34
35
```python { .api }
36
class InvalidArgumentError(PublicError):
37
"""
38
Client specified an invalid argument.
39
40
Corresponds to HTTP 400 Bad Request or Google error code INVALID_ARGUMENT.
41
"""
42
43
http_code = 400
44
45
def __init__(self, details=None):
46
"""
47
Initialize an InvalidArgumentError.
48
49
Args:
50
details (str, optional): Public error message details
51
"""
52
```
53
54
### Not Found Errors
55
56
HTTP 404 Not Found errors for missing resources.
57
58
```python { .api }
59
class NotFoundError(PublicError):
60
"""
61
Some requested entity (e.g., file or directory) was not found.
62
63
Corresponds to HTTP 404 Not Found or Google error code NOT_FOUND.
64
"""
65
66
http_code = 404
67
68
def __init__(self, details=None):
69
"""
70
Initialize a NotFoundError.
71
72
Args:
73
details (str, optional): Public error message details
74
"""
75
```
76
77
### Authentication Errors
78
79
HTTP 401 Unauthorized errors for authentication failures.
80
81
```python { .api }
82
class UnauthenticatedError(PublicError):
83
"""
84
Request does not have valid authentication credentials for the operation.
85
86
Corresponds to HTTP 401 Unauthorized or Google error code UNAUTHENTICATED.
87
Automatically includes required WWW-Authenticate header.
88
"""
89
90
http_code = 401
91
92
def __init__(self, details=None, *, challenge):
93
"""
94
Initialize an UnauthenticatedError.
95
96
Args:
97
details (str, optional): Public error message details
98
challenge (str): WWW-Authenticate HTTP header value per RFC 7235
99
"""
100
```
101
102
### Permission Denied Errors
103
104
HTTP 403 Forbidden errors for authorization failures.
105
106
```python { .api }
107
class PermissionDeniedError(PublicError):
108
"""
109
The caller does not have permission to execute the specified operation.
110
111
Corresponds to HTTP 403 Forbidden or Google error code PERMISSION_DENIED.
112
"""
113
114
http_code = 403
115
116
def __init__(self, details=None):
117
"""
118
Initialize a PermissionDeniedError.
119
120
Args:
121
details (str, optional): Public error message details
122
"""
123
```
124
125
## Usage Examples
126
127
### Basic Error Handling
128
129
```python
130
from tensorboard.errors import NotFoundError, InvalidArgumentError
131
132
def load_run_data(run_name):
133
if not run_name:
134
raise InvalidArgumentError("Run name cannot be empty")
135
136
if not os.path.exists(f"./logs/{run_name}"):
137
raise NotFoundError(f"Run '{run_name}' not found in logs directory")
138
139
# Load and return run data
140
return load_data(f"./logs/{run_name}")
141
```
142
143
### Authentication Error with Challenge
144
145
```python
146
from tensorboard.errors import UnauthenticatedError
147
148
def protected_endpoint(request):
149
auth_header = request.headers.get('Authorization')
150
if not auth_header or not validate_token(auth_header):
151
raise UnauthenticatedError(
152
"Valid authentication token required",
153
challenge='Bearer realm="TensorBoard"'
154
)
155
156
# Process authenticated request
157
return process_request(request)
158
```
159
160
### HTTP Integration
161
162
When these errors are raised in TensorBoard's web interface, they are automatically caught and converted to appropriate HTTP responses:
163
164
- Error message becomes the response body
165
- `http_code` becomes the HTTP status code
166
- `headers` list is added to the HTTP response headers
167
- All error text is considered safe for public display
168
169
This design enables consistent error handling across TensorBoard's web API while maintaining security by ensuring error messages don't contain sensitive information.