Troubleshooting

This packaged help page keeps local AGILAB help links usable when the full public documentation is not available. The public troubleshooting guide remains the source of truth for detailed recovery steps.

A - Prerequisite

Run AGILAB through the managed uv commands or generated run configuration wrappers so the selected project environment is explicit.

B - List of Available Scripts

Use ./dev impact, ./dev bugfix, ./dev test, and the generated scripts under tools/run_configs/ for reproducible local checks.

C - Example Test Sequence

./dev impact
./dev bugfix
uv --preview-features extra-build-dependencies run python tools/sync_docs_source.py --verify-stamp

Known Limitations and Deprecations

Known limitations should include impact, workaround, and a migration or removal target. Avoid hiding deprecation warnings globally; fix the source or document the scoped workaround.

<UV> Sync Failed

If a dependency appears installed but cannot be imported, inspect the app manager and worker pyproject.toml files first. If the uv cache is corrupted, run uv cache clean and retry.

<DASK> Debug Issue

When PyCharm debugger asyncio patches conflict with Dask, disable the debugger asyncio REPL option and rerun the local reproduction before changing cluster code.

<PYCHARM> Run/Debug Configuration is Broken

Regenerate run configuration wrappers after editing PyCharm configuration files. If a worker environment did not install, debug the app install first, then rerun pycharm/setup_pycharm.py.

Public docs: AGILAB troubleshooting.