Skip to content

Troubleshooting

Jump to bottom
PCART Bot edited this page May 11, 2026 · 4 revisions

Troubleshooting Guide

Common issues and solutions for PCART.

Installation Issues

Python Version Error

Problem: Python 3.9+ is required

Solution: Ensure you are using Python 3.9 or higher:

python --version

dill Not Found

Problem: ModuleNotFoundError: No module named 'dill'

Solution: Install dill in your environments:

pip install dill

Configuration Issues

Invalid JSON Format

Problem: JSONDecodeError when running PCART

Solution:

  • Ensure your JSON is valid (no trailing commas, proper quotes)
  • Use a JSON validator to check your configuration file
  • On Windows, use double backslashes (\\) or forward slashes (/) in paths

Path Not Found

Problem: FileNotFoundError: Project path does not exist

Solution:

  • Verify projPath is an absolute path, not relative
  • Check that the path exists on your filesystem
  • On Windows, ensure backslashes are properly escaped in JSON

Virtual Environment Path Error

Problem: Virtual environment path does not exist

Solution:

  • Verify currentEnv and targetEnv paths are correct
  • Use full absolute paths to virtual environment root directories, not the Python executable
  • On Windows, PCART looks for python.exe at <env>/python.exe and <env>/Scripts/python.exe

runCommand Not Recognized

Problem: UnsupportedRunCommand or command execution fails with "not found"

Solution:

  • PCART supports these runCommand formats: python, python3, py -X.Y, python -m, and console scripts (e.g., pytest, flask run)
  • The Python executable or console script must exist in the configured virtual environment
  • On Windows, the py launcher version selector (-3.9, -3) is automatically stripped — the actual Python comes from currentEnv/targetEnv
  • On Linux, console scripts are resolved from <env>/bin/; on Windows, from <env>/Scripts/

Runtime Issues

Library API Extraction Fails

Problem: extractLibAPI.py fails or times out

Solution:

  • Ensure the virtual environments have the correct library versions installed
  • Check that the library is importable in the virtual environment
  • Pre-extracted APIs are available in LibAPIExtraction/ directory

Missing Library API Definition Files

Problem: FileNotFoundError: [Errno 2] No such file or directory: 'LibAPIExtraction/{libName}/{libName}{version}'

Cause: The library's API definition files have not been pre-extracted for the specified version.

Solution: Run extractLibAPI.py to extract the API definitions for the missing version(s):

python extractLibAPI.py -cfg {config_file}.json

Replace {config_file} with your configuration file name (e.g., aiofiles1).

pkl Generation Fails

Problem: Failure to generate PKL in current version

Cause: The instrumented project failed to run in currentEnv. This typically means the project has runtime errors or missing dependencies.

Solution:

  • Check that the project runs successfully on its own in the current version environment
  • Ensure dill is installed in currentEnv
  • Check the terminal output for the run workspace path (printed as Run workspace: ... at the start of each run), then look in <workspace>/Report/<project>_fixed_log.txt
  • Check the exported report under Report/runs/{run_id}/{command_id}/
  • Verify that runCommand and runFilePath are correctly set

pkl Load Error in Target Version

Problem: Failed to load pkl in target version X.X.X: Ran out of input or similar dill error

Cause: The pkl file generated in the current environment cannot be deserialized in the target environment (common when library object formats change between versions).

Solution: This is handled automatically — PCART re-instruments and re-generates the pkl in targetEnv. If it persists after re-generation, check Report/<project>_fixed_log.txt.

pkl Save Failed (manifest save_failed)

Problem: Manifest shows "status": "save_failed" for a candidate

Cause: The runtime receiver object could not be serialized by dill (common with locked resources, database connections, or C extension objects).

Solution:

  • PCART automatically falls back to the __expr candidate (string expression) if the __object candidate fails
  • If both fail, the API call falls back to static matching only
  • Check <workspace>/Copy/pkl/<artifact_id>.manifest.json for detailed error information. The workspace path is printed at the start of each run.

Compatibility Analysis Fails

Problem: PCART stops during compatibility analysis

Solution:

  • Ensure your project runs successfully in the currentEnv environment (targetEnv is only used for API signature inspection and repair validation)
  • Check that the library version in currentEnv matches your configuration
  • Verify the library is importable in targetEnv

Repair Fails

Problem: Some APIs are not repaired successfully

Solution:

  • PCART repairs all incompatible calls at the AST level. pkl availability only determines validation method: dynamic (run repaired code) vs static (signature check).
  • If repair status is Unknown and the error mentions dill, the parameter values may not be serializable
  • Check the repair report in Report/runs/{run_id}/{command_id}/ for details on which validation path was used
  • Some compatibility issues may require manual intervention

Interpretation Issues

"Not Covered" APIs

Problem: Many APIs show "Coverage: No"

Cause: These APIs are not invoked in the executed code paths.

Solution: This is normal behavior. PCART only analyzes APIs that are actually called at runtime.

"Unknown Compatible" Status

Problem: Some APIs show "Unknown Compatible"

Cause: PCART cannot determine compatibility through static analysis alone.

Solution: This is expected for some complex API usages. The dynamic matching phase provides more accurate results.

Getting Help

If you encounter an issue not covered here:

  1. Check the repair report in Report/runs/{run_id}/{command_id}/ for detailed error information
  2. Check <workspace>/Copy/pkl/ for manifest files with save_failed status (workspace path is printed at the start of each run)
  3. Verify your configuration file is correct
  4. Ensure all prerequisites are installed
  5. Check the GitHub Issues

Related Pages

Clone this wiki locally