Skip to content

Add download preflight and stuck-pull guidance to local-ai-use - #106

Open
sreeram-11 wants to merge 2 commits into
mainfrom
sreeram/pull-preflight-guidance
Open

Add download preflight and stuck-pull guidance to local-ai-use#106
sreeram-11 wants to merge 2 commits into
mainfrom
sreeram/pull-preflight-guidance

Conversation

@sreeram-11

@sreeram-11 sreeram-11 commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

When a model download targets a bad path (out of space, no write permission, quota, read-only mount), the pull fails slowly and silently, but the console keeps printing Progress: NN% while the real error only shows up in the server log. This adds guidance so the agent catches that up front and diagnoses a stuck pull instead of waiting through silent retries.


Details

  • Preflight before pulling: check GET /api/v1/system-info, which reports models_dir (where the download lands) and a model_storage block with free_bytes / total_bytes. If free space is short of the model size, tell the user the path and stop rather than starting a doomed pull.
  • Detect a broken pull: a healthy pull ends with a success line; a broken one keeps printing Progress: NN% while the write error surfaces only in the server log. If a pull stalls, read the server log (typically lemonade-server.log in the OS temp dir) for the real error (e.g. a write failure like CURL code 23, or an out-of-space message) and surface it to the user.

Why

  • From dogfooding feedback: on a machine where the download path was a quota-limited network mount, pulls failed after minutes of silent retries with no actionable message.

@sreeram-11
sreeram-11 requested a review from danielholanda July 20, 2026 17:16
@danielholanda

Copy link
Copy Markdown
Collaborator

@sreeram-11 Were you able to validate that your changes resolve the issue in the affected scenarios (e.g., downloading a model when the system is out of disk space, lacks write permissions, or uses a read-only mount)? If so, which agent/model did you use?

@sreeram-11

Copy link
Copy Markdown
Collaborator Author

The changes are doc-only (two additions: a preflight step in local-ai-rule.md and a troubleshooting row in SKILL.md), and I validated them against a Lemonade v11.5.0 install on my Windows Strix Halo, using Claude Opus 4.8.

What's verified: The mechanisms the guidance relies on are real and correct.

  • **GET /api/v1/system-info** returns exactly what the preflight needs: model_storage.path (the actual download location, C:\Users<user>.cache\huggingface\hub) and model_storage.free_bytes.
  • The preflight decision logic is correct against live data: It proceeds when there's room and produces a clear "stop + report path/free/required space" when the model wouldn't fit.
  • The server log the guidance points to is real and in the documented place (lemonade-server.log in the OS temp dir), and it carries the download/error lines an agent would read to diagnose a stuck pull.

So the core of the fix (check system-info before pulling, and read the log if a pull stalls) is validated end to end on the parts that matter.


One useful finding while testing the failure paths:

  • I tried to force a broken-path download by redirecting the cache with HF_HOME/HF_HUB_CACHE, but the model still downloaded fine to the normal cache.
    • This is because the download is handled by the already-running lemond service, which reads its environment at startup and doesn't pick up env vars set in a later shell.
  • This reinforces the design choice in this PR where we intentionally rely on the server's system-info endpoint to learn the real download location and free space, rather than guessing at env vars, which we've confirmed a running service ignores.

To reproduce the three failure states (full disk / no write permission / read-only mount) as genuine live pulls, they need to be created where the lemond service actually writes, that is, a disposable environment with lemond configured to write to a small/locked/read-only volume.

  • I kept my machine's defaults untouched, so I didn't reconfigure the live service.
  • I can run that disposable-environment pass if we want the failure paths reproduced live, but the guidance's underlying mechanism is already confirmed working.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants