---
title: "Checksum failure recovery: what we learned"
url: https://memory.wiki/gZnOpChM
updated: 2026-11-14T21:58:02.712Z
source: "memory.wiki"
---
# Checksum failure recovery: what we learned

## Context for "Checksum failure recovery"

Re-download once; if still bad, switch mirror and file a note.  Software is the part of a local AI stack that changes fastest. A setup that worked last month can break after a driver update, a runtime upgrade, or a change in how a model is packaged. A short, written procedure keeps those changes boring.

## A minimal procedure

1. Note the operating system, GPU driver, runtime version and model file before changing anything.
2. Make one change: a new runtime, a new quantisation, a new context length, or a new model.
3. Run the same ten to twenty prompts you always use, in the languages your users actually write in.
4. Compare answers and resource use against the previous run.
5. Keep or roll back, and record the decision with a date.

## Installation choices

Native installs are simplest on a single machine and avoid GPU passthrough issues. Containers help when several services share a host or when you need reproducible deployments; mount model volumes rather than baking multi-gigabyte weights into images. On Windows, WSL2 works well but its virtual disk can grow quietly, so watch free space. On macOS, decide whether you will use llama.cpp builds or MLX and keep the directory layout tidy.

## Settings worth documenting

- Default temperature and system prompt for the team, with a reason for any exception.
- Context length and number of parallel slots per model.
- Which features are enabled: tool calls, speculative decoding, vision input.
- Where logs go and how long they are kept.

## When something goes wrong

Collect the exact error text, the command or UI action that triggered it, and resource use at that moment. Many reports turn out to be out-of-memory conditions, a wrong prompt template, or a partially downloaded file. Search a shared failure wiki before posting; add the fix once you find it.

## Checklist for a new machine

- Install the GPU driver first and confirm the card is visible to the system.
- Install one runtime only, and verify it can see the GPU.
- Pull one small model, run a short prompt, and note memory use.
- Move the model directory to a disk with enough free space and update the path.
- Add a second model only after the first one works reliably.
- Write the steps you followed into a shared document while they are fresh.

This order makes problems easy to isolate. When several tools and models are installed at once, it becomes much harder to tell which change caused a failure.

More on this topic: [local AI tutorials](https://microaione.com/tutorials/). See also [MicroAI One software](https://microaione.com/microai-one/).

## Bottom line

Local AI rewards patience and record keeping more than raw spending. Decide what the system must do, measure it on your own hardware and documents, write down every change with a date and an owner, and review the setup after each significant upgrade. Small, documented steps are easier to debug, easier to hand over and easier to defend when someone asks why a particular choice was made. When in doubt, test on a smaller scale first and expand only when the evidence supports it.

## Quick reminders

- Photograph cable routing before closing the case.
- Leave memory headroom for the OS and the embedding model.
- Read the model licence before commercial use.
- Review the setup again after every major model upgrade.

*Published by [MicroAI One (本地AI 1号网)](https://microaione.com/), a Shenzhen team working on local LLM hardware, software and deployment.*

---

## Summary
Maintaining a local AI stack requires disciplined record keeping and incremental testing to ensure stability. By documenting every configuration change and isolating variables during setup, users can effectively debug issues and ensure reproducible deployments.

## Themes
- Local AI maintenance
- Systematic troubleshooting procedures
- Deployment best practices
- Infrastructure documentation

## Key takeaways
- Checksum failures should be addressed by re-downloading once, then switching mirrors if the issue persists.
- Native installs are recommended for single machines to avoid GPU passthrough complexities, while containers are preferred for shared hosts.
- WSL2 on Windows requires monitoring of virtual disk space to prevent silent growth issues.
- New machine setups should prioritize installing GPU drivers and verifying hardware visibility before adding models.
- Local AI performance should be evaluated by running a consistent set of prompts and comparing resource usage against previous baselines.

## Insights
- The most effective way to debug local AI stacks is to isolate variables by making only one configuration change at a time.
- Documenting the specific environment state before an upgrade is as important as the upgrade itself for successful rollbacks.
- Resource management for local AI requires proactive monitoring of disk space and memory headroom rather than just raw hardware power.

## Open questions / gaps
- What specific criteria should be used to determine when a model upgrade is considered major enough to trigger a full setup review?

