Troubleshooting

Start with the smallest local example before troubleshooting a scientific engine or cluster.

Installation or tool discovery fails

python -m pip check
python -m pip show caddforge-core
caddforge list-tools

Use the same environment for installation and execution. Plugins install core automatically but may need external executables or conda-managed dependencies. pip check checks Python dependency metadata; it cannot verify an engine or GPU. See installation and the selected plugin page. Candidate versions are not necessarily published; use compatible source tags until release.

If discovery raises an import error, inspect its first failing module and install the plugin's declared requirements. Ordinary tool discovery loads installed entry points; a broken scientific plugin can prevent discovery. Do not assume it is ignored.

PyOCL or Java fails

Install the distribution pyocl-idor>=0.8.3; Python code imports it as pyocl. For a missing Python dependency:

python -m pip install "pyocl-idor>=0.8.3"

PyOCL requires Java 21 or newer. Set JAVA_HOME to the intended Java installation. If JPype cannot find libjvm, verify that this runtime is installed and discoverable. An UnsupportedClassVersionError can indicate an older Java runtime loading the bundled Java 21 helper classes. Check the runtime JPype finds:

java -version
python -c "import jpype; print(jpype.getDefaultJVMPath())"

If the old pyocl distribution is installed, remove it before installing pyocl-idor: both distributions own the same Python import namespace. Restart Python or the notebook kernel after changing a running JVM.

Configuration or input paths are rejected

caddforge show-config datascience distribution-diagnostics
caddforge run datascience distribution-diagnostics --help

Compare fields and types with the installed tool's template. Supply required paths, including authoritative ligand chemistry for molecular workflows. CLI workflow inputs are resolved from the submission directory. Built-in pipeline input_path values resolve relative to the pipeline YAML. Use absolute paths when diagnosing ambiguity. A schema-valid file can still refer to missing or scientifically unsuitable input.

Job is missing or failed

caddforge list-jobs
caddforge status <job-id>
caddforge logs <job-id>

Use the original working directory and registry. The logs command shows stdout; inspect stderr.log directly in the recorded run directory when needed. Inspect saved configuration, metadata.json, and the canonical result, then the first error in the logs. An absent result may mean the job is still running, not that it succeeded. Preserve the original run; use a new run directory for a corrected submission.

Slurm submission or execution fails

Run caddforge backend-check --help and test the intended environment with that command. Check scheduler state, partition/account/time limits, environment accessibility, node filesystem permissions, and engine availability on the compute node. A successful sbatch submission does not establish scientific completion. See Slurm setup for packed environments and wheelhouses.

Browser-based interfaces do not open

For installed docs, verify caddforge-docs is installed in the CLI environment:

caddforge docs --host localhost --no-browser

Open the printed URL manually. Choose a different --port if the requested port is occupied. For a remote server, select a reachable --host and an appropriate network or SSH tunnel; loopback addresses are local to the machine running the server. GUI configuration and docs serving are separate commands.

Prepare a useful bug report

Include package versions, platform, backend, a minimal synthetic reproducer, expected behavior, actual behavior, and the relevant error. Remove credentials, personal paths, unpublished compounds, receptor structures, and research data before sharing configurations, logs, screenshots, or registry files. See contributing.