Troubleshooting

Line	What it means
`batch unavailable: <why>`	The source did not deliver a batch (network error, 4xx/5xx, refused redirect) and no cached one could stand in: everything compiles from source.
`batch signature invalid`, `batch stale: ...`, `batch expired at ...`, `batch sequence N is older than M`, `batch lifetime ...`, `batch malformed`	A batch was delivered but failed that check; it is never used, and nothing installs this run. A stale or expired batch usually means the source stopped publishing.
`batch unavailable: offline, no cached batch`	`PRECOMPILED_OFFLINE=1` is set and this home holds no batch yet: everything compiles from source. Run once online to fill the cache.
`source unreachable (<why>); using the cached batch`	The network failed; a cached batch that still passes every check stood in. When the source failed to connect, manifests and files not in the cache then miss at once: it is not asked again in that run.
`no fresh batch (<why>); N installed builds kept, not rechecked`	Earlier installs stay as they are until a batch is available again.
`clock is before ...`	The machine's clock is wrong (a device before NTP). Set it; nothing installs until then.
`cache dir ... is not writable; using ...`	The run used a fresh cache under `_build`. Fix the permissions or set `PRECOMPILED_HOME`.
`FAIL cache refused (... remove it)`	A cache entry or dir is a symlink or not a plain file; it is never followed. Remove the path the line names.
`MISS reads Mix.target() at compile time ...`	Rule 8: no build was made for this target name.
`internal error, compiling from source`	A bug in this library; the build carries on. Please report it with the line.

PRECOMPILED_DEBUG=1 also lists the dependencies that were not candidates and why. PRECOMPILED=0 rules this library out completely: it removes its installs and Mix compiles everything.

Known limitations

Mix's :lockfile option is passed through to Mix.install/2 but not used for the precompiled step, so an external lockfile can make Mix re-resolve and recompile what was just installed.
:config and :config_path are not applied before the check, so a dependency whose compile-time config they change misses, or is placed and then recompiled by Mix's config-outdated check. Never a wrong build.
MIX_INSTALL_RESTORE_PROJECT_DIR is ignored by the precompiled step.
One online key signs both the root and the batches (see Trust).
On a machine with no trust state yet (a fresh install, or one pointed at a new :home), an older batch issued within the last 24 hours still passes the freshness checks: there is no stored sequence yet to catch it as a rollback.
A mirror that withholds newer roots leaves a fresh :home on the shipped root; a root is only adopted when the source actually serves it.
The provenance file (.mix/precompiled.json under a dependency's build dir) is what tells an installed build from a compiled one; anyone who can write _build can forge it, the same trust _build already carries.
Builds installed by an earlier version of this library carry no provenance file and are not rechecked; they are rechecked only after mix deps.clean --build or a clean _build (for install/2, a forced install) has them installed again.
Builds made for a Nerves system may have stripped beams: protocols they define are not consolidated and Dialyzer has no types for them (a run says how many).
With the Nerves fork, nerves.init calls this library itself. The library does nothing under help, clean and precompiled.* tasks, but the hook still runs its own setup first; the fork's nerves.init skip list should name precompiled.* as well (a change on the fork's side).
Released nerves 1.x has no Nerves.build_plan/0, so no Nerves system is known and only pure_elixir builds match (see Nerves).

← Previous Page Trust