Troubleshooting & Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
Troubleshooting and error handling in the Duplicate Code Detection Tool are primarily governed by return codes, threshold validations, and defensive file operations. The system is designed to provide clear feedback when inputs are invalid, files are inaccessible, or code duplication exceeds safety limits defined by the user.
At a high level, the tool distinguishes between execution failures (e.g., bad file paths) and policy failures (e.g., code being too similar). This distinction allows for seamless integration into CI/CD pipelines where different types of errors require different responses, such as blocking a merge or simply logging a warning.
Execution Return Codes
The core logic utilizes an enumeration to represent the outcome of a detection run. This allows calling modules to programmatically determine if a failure occurred due to environmental issues or code quality violations.
| Return Code | Value | Description |
|---|---|---|
SUCCESS | 0 | The analysis completed successfully and all duplications are within allowed thresholds. |
BAD_INPUT | 1 | The tool encountered invalid paths, non-existent files, or insufficient file counts to perform a comparison. |
THRESHOLD_EXCEEDED | 2 | Analysis completed, but at least one file pair exceeded the fail_threshold. |
Sources: [duplicate_code_detection.py:31-34](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L31-L34), [core.py:23](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/core.py#L23)
Error Handling Flow
The following diagram illustrates how the run function handles various error states during initialization and execution:
The tool employs try-except blocks when reading files to ensure that a single corrupt or unreadable file does not crash the entire analysis process.
Sources: [duplicate_code_detection.py:168-204](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L168-L204), [duplicate_code_detection.py:220-227](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L220-L227)
Input Validation & Exception Handling
File and Directory Validation
The tool strictly validates inputs before proceeding to heavy computation. In the run function, if a provided directory does not exist or if fewer than two source code files are found, the process aborts immediately with ReturnCode.BAD_INPUT.
if directories:
for directory in directories:
if not os.path.isdir(directory):
print("Path does not exist or is not a directory:", directory)
return (ReturnCode.BAD_INPUT, {})
# ...
if len(source_code_files) < 2:
print("Not enough source code files found")
return (ReturnCode.BAD_INPUT, {})
Sources: [duplicate_code_detection.py:171-196](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L171-L196)
File Content Processing
Errors during file reading are handled gracefully. Specifically, when opening files, the tool uses errors="surrogateescape" to recover from encoding errors in source files, preventing the script from terminating prematurely.
Sources: [duplicate_code_detection.py:220-227](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L220-L227)
Line of Code (LoC) Errors
The get_loc_count function wraps file reading in a try-except block. If the LoC count cannot be determined for a specific file, it returns -1 and prints a warning to the console rather than raising an exception.
Sources: [duplicate_code_detection.py:108-115](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L108-L115)
CI/CD and Integration Troubleshooting
When used within GitHub Actions or other CI/CD environments, additional error handling layers are present in run_action.py and entrypoint.sh.
GitHub Actions Environment Issues
The entrypoint.sh script checks for the presence of a Pull Request ID. If it is missing (e.g., the action is run on a standard push rather than a PR), the script exits with code 1.
if [ $pull_request_id == "null" ]; then
echo "Could not find a pull request ID. Is this a pull request?"
exit 1
fi
Sources: [entrypoint.sh:9-12](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/entrypoint.sh#L9-L12)
Report Size Limits
In run_action.py, the make_markdown_table function monitors the total character count of the generated Markdown report. If the report exceeds 65,000 characters (approaching GitHub's comment limits), the results are truncated, and a warning suffix is appended.
if markdown_characters > max_characters:
markdown += "\n" + WARNING_SUFFIX + " "
markdown += "Results were omitted because the report was too large. "
break
Sources: [run_action.py:44-48](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/run_action.py#L44-L48)
API Interaction Failures
The tool attempts to post or update comments on GitHub PRs. If the API request fails, it prints the status code and error message to the logs but does not necessarily fail the build unless the ReturnCode from the detection logic itself was non-zero.
Sources: [run_action.py:170-175](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/run_action.py#L170-L175), [run_action.py:186-191](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/run_action.py#L186-L191)
Summary of Configuration-Based Error Triggers
Users can configure the sensitivity of the tool, which directly impacts the return codes and troubleshooting outputs.
| Option | Effect on Error Handling |
|---|---|
--fail-threshold | Determines when THRESHOLD_EXCEEDED is returned. |
--ignore-threshold | Filters out low-similarity data, potentially preventing "Report too large" errors. |
--only-code | If set to True, errors in ast.parse (e.g., syntax errors in Python) might cause file skipping. |
--project-root-dir | If path is invalid, returns BAD_INPUT. |
Sources: [duplicate_code_detection.py:126-160](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/duplicate_code_detection.py#L126-L160), [core.py:133-145](https://github.com/flext-sh/duplicate-code-detection-tool/blob/b28e9168e6d32869e332323831943fa8987bbfd8/core.py#L133-L145)
The Duplicate Code Detection Tool ensures robustness by combining pre-analysis input validation with defensive runtime error handling, allowing developers to identify whether issues stem from their environment, configuration, or the codebases being analyzed.