image-debug

image-debug

projtool builds project images by spinning up a one-shot AutoDL "builder" instance, running the project's setup.sh inside it, and (on success) saving the result as a custom image. This skill activates when something goes wrong during setup.sh. Most failures fall into a small number of categories, listed below — read the relevant references/ file before proposing a fix.

Workflow

1. Don't tear down on first failure. The builder instance is alive and has all the partial state. Closing it loses minutes of debug context.
2. Read the tail of stderr. mcp__projtool__remote_exec returns stderr_tail (and stdout_tail) inline in the response; the full output is written to the file at log_path in the result. The error message is almost always in the last 30 lines of stderr_tail.
3. Match the error to a category (below). Read the matching reference.
4. Propose a fix. Either patch setup.sh locally + push it to the instance via write_remote_file, or run the fix command directly via remote_exec to validate before bake-in. For non-trivial changes, patching setup.sh is preferred — it makes the next build idempotent. For AutoDL PyTorch base images, make the first line after set -euo pipefail export Miniconda onto PATH: export PATH="/root/miniconda3/bin:$PATH". Some non-interactive SSH shells do not source bashrc, so plain python / python3 may otherwise be missing even though the image has conda.
5. Re-run the failed step, not the whole setup.sh. Most steps are idempotent (apt-get, pip install). Only re-run the full script when confident the earlier steps will no-op cleanly.
6. On success, confirm the build passes end-to-end before saving. Then: image_save (non-blocking — returns pending_image_uuid immediately) → poll image_save_status until image_status='ready' → image_build_finalize. Saving an image with hidden partial state (e.g., wrong CUDA toolkit) creates a long-tail bug.
7. On give-up, image_build_abandon releases the builder. Don't leave builders running — they bill at GPU rates.