Newcomer First-Failure Recovery

This page is intentionally narrow.

Use it only for the first AGILAB proof path:

  • source checkout

  • built-in flight_project

  • local run

  • web UI first

If you are already debugging cluster mode, private apps, packaged install, or notebook-first flows, this is not the right page. Go to the broader Troubleshooting or FAQ pages instead.

Before anything else

Run the newcomer proof command once and keep its result as your baseline:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py

If you want the installer and seeded helper checks as part of the same proof:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py --with-install

Failure 1: uv is missing

Symptom:

  • uv: command not found

  • the install or newcomer proof command fails immediately before AGILAB starts

Recovery:

curl -LsSf https://astral.sh/uv/install.sh | sh
exec "$SHELL" -l
uv --version

Then rerun the newcomer proof:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py

Failure 2: ./install.sh --install-apps --test-apps fails

Symptom:

  • the installer exits non-zero

  • built-in apps are not usable afterwards

  • you only have partial setup under ~/log or ~/.agilab

Recovery:

./install.sh --install-apps --test-apps

If you need to inspect the latest installer log quickly:

dir="$HOME/log/install_logs"; f=$(ls -1t "$dir"/*.log 2>/dev/null | head -1); [ -n "$f" ] && echo "Log: $f" && tail -n 40 "$f"

Then rerun the proof command with install enabled:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py --with-install

Failure 3: the built-in app path is not found

Symptom:

  • Provided --active-app path not found

  • the PROJECT page does not point to the built-in flight demo

  • the newcomer proof command fails before the UI smoke completes

The expected built-in path in a source checkout is:

src/agilab/apps/builtin/flight_project

Recovery:

test -d src/agilab/apps/builtin/flight_project && echo OK || echo MISSING

If it is missing, you are likely not in the AGILAB source checkout you think you are, or the install did not finish cleanly. Return to the repo root and rerun:

./install.sh --install-apps --test-apps

Then rerun:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py

Failure 4: the web UI or About/ORCHESTRATE smoke fails

Symptom:

  • streamlit run src/agilab/About_agilab.py fails

  • the newcomer proof command reports a failing source ui smoke step

  • About or ORCHESTRATE raises exceptions during AppTest startup

Recovery:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py

If that fails, run the pages directly:

uv --preview-features extra-build-dependencies run streamlit run src/agilab/About_agilab.py

Then verify the built-in app can be resolved by path:

uv --preview-features extra-build-dependencies run python tools/apps_pages_launcher.py --active-app src/agilab/apps/builtin/flight_project

If the failure mentions package import or missing environment setup, rerun:

./install.sh --install-apps --test-apps

Failure 5: no fresh output appears under ~/log/execute/flight/

Symptom:

  • the UI starts, but your first proof does not end in visible evidence

  • ~/log/execute/flight/ has no fresh output

  • install may have seeded helper scripts but no useful run artifacts appeared

First confirm the newcomer proof still passes:

uv --preview-features extra-build-dependencies run python tools/newcomer_first_proof.py --with-install

Then inspect the expected output directory:

ls -la ~/log/execute/flight

If the helper scripts are missing, rerun the source installer for the built-in app:

uv --preview-features extra-build-dependencies run python src/agilab/apps/install.py src/agilab/apps/builtin/flight_project --verbose 1

Then relaunch the UI and follow the first-proof path again:

  1. PROJECT -> select src/agilab/apps/builtin/flight_project

  2. ORCHESTRATE -> run the local install/distribute/run path

  3. PIPELINE -> confirm the generated step exists

  4. ANALYSIS -> confirm one visible result exists

When you are past the newcomer hurdle

You are done with this page when all of the following are true:

  • the newcomer proof command returns PASS

  • AGILAB writes fresh output under ~/log/execute/flight/

  • the four-page path stays understandable as PROJECT -> ORCHESTRATE -> PIPELINE -> ANALYSIS

After that, go back to: