Troubleshooting#

Use this page when an agent or the web app stops before completing a workflow. Each item lists the symptom, likely cause, and the fastest fix.

Data File Not Found#

Symptom: A loader fails before processing and prints an attempted absolute path.

Probable cause: The path was typed relative to a different working directory, or the uploaded file was not mapped to the expected config field.

Fix: Use the absolute path shown in the error message, or re-upload the file and confirm the parsed configuration before running.

API Key Missing or Invalid#

Symptom: The app says the LLM provider is not initialized, or an agent fails while parsing a natural-language request.

Probable cause: The selected provider key is missing, expired, or belongs to a different provider.

Fix: Use demo mode for a no-key walkthrough, or enter the correct OPENAI_API_KEY, GEMINI_API_KEY, or ANTHROPIC_API_KEY before using the LLM-backed path.

Wrong ERT Instrument Declared#

Symptom: ERT loading returns needs_review and reports different declared and detected instruments.

Probable cause: The selected instrument does not match the file header or export format.

Fix: Change the instrument field in the confirmation form to the detected instrument, or re-export the file from the expected instrument software.

pyGIMLi or SimPEG Import Fails#

Symptom: The app or CLI reports that pygimli or SimPEG cannot be imported.

Probable cause: Optional inversion dependencies are not installed in the current Python environment.

Fix: Install the missing package in the active environment. For pyGIMLi, conda install -c gimli pygimli is usually the most reliable path.

Mesh Generation Fails#

Symptom: The inversion stops during mesh creation or reports invalid electrode geometry.

Probable cause: Electrode positions are missing, duplicated, non-monotonic, or outside the expected survey geometry.

Fix: Inspect the electrode file, remove duplicates, and verify units and coordinate columns before rerunning.

Inversion Diverges#

Symptom: Chi-squared grows between attempts, or the model disagrees with the data more after an update.

Probable cause: The starting model, damping value, data errors, or electrode geometry are inconsistent with the observations.

Fix: Increase damping (lambda), check electrode positions, and inspect noisy data points before launching another full inversion.

Streamlit Upload Size Exceeded#

Symptom: Upload fails in the hosted app, or a data-loading agent rejects a large file.

Probable cause: The file is too large for hosted Streamlit execution.

Fix: Run the app locally for large datasets, or split/compress the data before uploading. Files larger than 500 MB should be treated as local-workflow inputs.

Joint ERT+SRT Geometry Mismatch#

Symptom: A joint workflow stops after loading both ERT and SRT data.

Probable cause: The ERT electrodes and SRT receiver/source geometry do not describe the same profile, coordinate system, or domain.

Fix: Confirm that both files use the same units, origin, profile direction, and survey extent.

LLM Rate Limit or Quota Error#

Symptom: Natural-language parsing or interpretation fails with a provider rate-limit, quota, or billing message.

Probable cause: The provider account is out of quota or temporarily throttled.

Automatic retry (v0.3+): All three providers now retry automatically up to three times with exponential back-off (1 s, 2 s, 4 s) whenever the error text contains rate limit, resource exhausted, quota, too many requests, or 429. Most transient throttle errors resolve within one retry and require no user action.

If all three attempts fail (extended outage or hard quota cap):

  • Wait a few minutes and re-run the workflow.

  • Switch provider or model via the llm_provider / model parameters.

  • Use dry_run=True or demo mode for a no-LLM walkthrough.

  • For persistent quota issues, check your provider billing dashboard.

Resuming a Failed or Interrupted Workflow#

Symptom: A workflow crashes or is killed mid-run (power failure, out-of-memory, unexpected error at step 3 of 5). You do not want to repeat the expensive steps that already finished.

Fix (v0.3+): Restart with resume=True.

from PyHydroGeophysX.agents import AgentCoordinator

coordinator = AgentCoordinator(api_key=api_key, output_dir='./results')
# ... register agents ...

# Skip steps that already have a checkpoint
results = coordinator.execute_workflow(config, resume=True)

The coordinator looks for <output_dir>/checkpoints/<step>.pkl files. Any step that has a valid checkpoint is loaded from disk rather than re-executed. Steps that failed or never ran are executed normally.

To force a full re-run despite existing checkpoints, remove the checkpoints/ folder:

rm -rf ./results/checkpoints/

3D Mesh Generation Fails (gmsh not found)#

Symptom: The 3D Mesh Builder app or Mesh3DCreator raises a gmsh not found or FileNotFoundError for the GMSH executable.

Probable cause: GMSH is not installed or not on PATH.

Fix:

# Conda (recommended)
conda install -c conda-forge gmsh

# Or download from https://gmsh.info and add the binary to PATH.

After installing, verify with:

gmsh --version

Then re-launch the app: python -m PyHydroGeophysX.gui_mesh3d

3D Electrode View is Blank#

Symptom: The Electrode View tab in the 3D Mesh Builder shows no chart or a plain axis without points.

Probable cause: plotly is not installed in the active environment.

Fix:

pip install plotly

Quality Loop Never Reaches Threshold#

Symptom: The quality loop exhausts all attempts and returns needs_review.

Probable cause: Automatic parameter adjustment improved the result too little, or the data geometry/noise prevents a reliable model.

Fix: Review the attempt log, adjust damping or data errors manually, and treat the result as preliminary until the residuals and geometry are checked.

Ambiguous Natural-Language Request#

Symptom: The context agent returns needs_review and lists missing fields.

Probable cause: The request does not specify enough information, such as data type, file path, instrument, or inversion mode.

Fix: Add the missing fields in the request or edit them in the confirmation form before running.