0
# Error Handling System
1
2
Exception hierarchy and error management functions for handling various types of errors that can occur during scanning and rule processing.
3
4
## Capabilities
5
6
### Exception Classes
7
8
Comprehensive exception hierarchy for different error types.
9
10
```python { .api }
11
class SemgrepError(Exception):
12
"""
13
Base exception class for all Semgrep-specific errors.
14
15
All custom semgrep exceptions inherit from this base class
16
to enable catch-all error handling.
17
18
Attributes:
19
- code (int): Error code for programmatic handling
20
- level (str): Error level (ERROR, WARNING, INFO)
21
- span_context (dict): Source code context if applicable
22
"""
23
def __init__(self, message, code=None, level="ERROR"): ...
24
25
class SemgrepCoreError(SemgrepError):
26
"""
27
Errors from the semgrep-core engine.
28
29
Raised when the core analysis engine encounters issues
30
during pattern matching or AST analysis.
31
32
Attributes:
33
- core_error_type (str): Type of core engine error
34
- rule_id (str): Rule ID that caused the error if applicable
35
"""
36
def __init__(self, message, core_error_type=None, rule_id=None): ...
37
38
class InvalidScanningRootError(SemgrepError):
39
"""
40
Invalid scan root directory error.
41
42
Raised when the specified scanning root directory
43
doesn't exist or isn't accessible.
44
45
Attributes:
46
- attempted_path (str): Path that was attempted
47
"""
48
def __init__(self, message, attempted_path=None): ...
49
50
class ErrorWithSpan(SemgrepError):
51
"""
52
Errors with source code location context.
53
54
Provides additional context about where in the source
55
code the error occurred.
56
57
Attributes:
58
- span (dict): Source location information
59
- file_path (str): File where error occurred
60
- line_number (int): Line number of error
61
"""
62
def __init__(self, message, span=None, file_path=None): ...
63
64
class InvalidRuleSchemaError(SemgrepError):
65
"""
66
Invalid rule schema validation error.
67
68
Raised when a rule doesn't conform to the expected
69
YAML schema or has invalid syntax.
70
71
Attributes:
72
- rule_id (str): ID of the invalid rule
73
- schema_errors (list): List of specific schema violations
74
"""
75
def __init__(self, message, rule_id=None, schema_errors=None): ...
76
77
class UnknownLanguageError(SemgrepError):
78
"""
79
Unsupported programming language error.
80
81
Raised when trying to analyze code in a language
82
that semgrep doesn't support.
83
84
Attributes:
85
- language (str): The unsupported language
86
- available_languages (list): List of supported languages
87
"""
88
def __init__(self, message, language=None, available_languages=None): ...
89
90
class DependencyResolutionSemgrepError(SemgrepError):
91
"""
92
Dependency resolution errors.
93
94
Raised when semgrep cannot resolve project dependencies
95
for dependency-aware analysis.
96
97
Attributes:
98
- dependency_manager (str): Type of dependency manager (npm, pip, etc.)
99
- resolution_errors (list): Specific resolution failures
100
"""
101
def __init__(self, message, dependency_manager=None, resolution_errors=None): ...
102
```
103
104
### Error Management Functions
105
106
Functions for tracking and filtering errors.
107
108
```python { .api }
109
def mark_semgrep_error_as_reported(error):
110
"""
111
Mark a semgrep error as having been reported to avoid duplicates.
112
113
Parameters:
114
- error (SemgrepError): Error to mark as reported
115
116
Returns:
117
None
118
"""
119
120
def is_semgrep_error_already_reported(error):
121
"""
122
Check if a semgrep error has already been reported.
123
124
Parameters:
125
- error (SemgrepError): Error to check
126
127
Returns:
128
bool: True if error was already reported
129
"""
130
131
def select_real_errors(errors):
132
"""
133
Filter for actual errors versus warnings from error list.
134
135
Parameters:
136
- errors (list): List of error objects to filter
137
138
Returns:
139
list: Filtered list containing only real errors
140
"""
141
142
def format_error_message(error, include_span=True):
143
"""
144
Format error message for display.
145
146
Parameters:
147
- error (SemgrepError): Error to format
148
- include_span (bool): Whether to include source code context
149
150
Returns:
151
str: Formatted error message
152
"""
153
```
154
155
## Constants
156
157
### Exit Codes
158
159
Standard exit codes used by semgrep for different outcomes.
160
161
```python { .api }
162
OK_EXIT_CODE = 0 # Scan completed successfully, no findings
163
FINDINGS_EXIT_CODE = 1 # Scan completed successfully, findings found
164
FATAL_EXIT_CODE = 2 # Fatal error occurred during scan
165
INVALID_LANGUAGE_EXIT_CODE = 3 # Invalid or unsupported language specified
166
UNPARSEABLE_YAML_EXIT_CODE = 4 # Invalid YAML in configuration
167
NEED_ARBITRARY_CODE_EXEC_EXIT_CODE = 5 # Arbitrary code execution required
168
MISSING_CONFIG_EXIT_CODE = 6 # No configuration provided
169
INVALID_CONFIG_EXIT_CODE = 7 # Invalid configuration
170
UNPARSEABLE_PATTERN_EXIT_CODE = 8 # Invalid pattern syntax
171
FATAL_RULE_PARSE_ERROR_EXIT_CODE = 9 # Fatal rule parsing error
172
```
173
174
### Error Levels
175
176
```python { .api }
177
class ErrorLevel:
178
"""
179
Error severity levels.
180
181
Values:
182
- ERROR: Critical errors that prevent operation
183
- WARNING: Issues that should be addressed but don't prevent operation
184
- INFO: Informational messages
185
"""
186
ERROR = "ERROR"
187
WARNING = "WARNING"
188
INFO = "INFO"
189
```
190
191
## Usage Examples
192
193
### Basic Error Handling
194
195
```python
196
from semgrep.error import SemgrepError, SemgrepCoreError, InvalidRuleSchemaError
197
from semgrep.run_scan import run_scan_and_return_json
198
199
try:
200
results = run_scan_and_return_json(target_manager, config)
201
except InvalidRuleSchemaError as e:
202
print(f"Rule validation failed: {e}")
203
print(f"Invalid rule: {e.rule_id}")
204
for schema_error in e.schema_errors:
205
print(f" - {schema_error}")
206
207
except SemgrepCoreError as e:
208
print(f"Core engine error: {e}")
209
if e.rule_id:
210
print(f"Rule causing error: {e.rule_id}")
211
212
except SemgrepError as e:
213
print(f"Semgrep error: {e}")
214
print(f"Error code: {e.code}")
215
print(f"Error level: {e.level}")
216
```
217
218
### Error Filtering and Reporting
219
220
```python
221
from semgrep.error import select_real_errors, mark_semgrep_error_as_reported
222
223
# Assume we have a list of errors from scanning
224
all_errors = [...] # List of various error types
225
226
# Filter for real errors (not warnings)
227
real_errors = select_real_errors(all_errors)
228
229
# Process each error
230
for error in real_errors:
231
if not is_semgrep_error_already_reported(error):
232
print(f"New error: {error}")
233
# Handle the error...
234
mark_semgrep_error_as_reported(error)
235
```
236
237
### Custom Error Handling
238
239
```python
240
from semgrep.error import SemgrepError, ErrorLevel
241
242
class CustomAnalysisError(SemgrepError):
243
"""Custom error for specific analysis failures."""
244
def __init__(self, message, analysis_type=None):
245
super().__init__(message, level=ErrorLevel.ERROR)
246
self.analysis_type = analysis_type
247
248
# Usage in custom analysis code
249
def custom_analysis():
250
try:
251
# Perform analysis...
252
pass
253
except Exception as e:
254
raise CustomAnalysisError(
255
f"Custom analysis failed: {e}",
256
analysis_type="dependency_analysis"
257
)
258
```