Common errors

Keep the full error text, then distinguish a configuration error from a runtime failure in a specific Pin. nix-pins status shows existing results and the last recorded failures.

Configuration fails to load

• Check the current working directory, --config, and --pins.
• Confirm <nixpkgs> resolves by running nix eval --impure --raw --expr 'toString <nixpkgs>'.
• Check target fields: do not mix target with legacy fields; GitHub targets must use owner/repo.
• URLs for pin.fetcher.url and pin.fetcher.zip must be functions such as version: "https://...", not plain strings.
• rev mappings must also return strings. Unsupported fields cause errors.

Deterministic configuration errors occur before Checkers run. Fix the declaration, then update again.

Version checks fail

GitHub 403 or 429 responses may indicate API rate limits. Supply a token as described in Runtime configuration. Do not write tokens into files you will commit.

Git checks rely on git ls-remote. Check connectivity, repository permissions, and mode. Branch mode requires branch; ref mode requires ref. If tag mode has no candidates, check the regular expressions and whether the repository has matching tags.

The npm Checker reads dist-tags and fails if the requested distTag does not exist. For URL Checker mismatches, inspect the response text and regex. Command Checkers must exit successfully and print a nonempty version.

Source fetching fails

Check that the original Version from the Checker corresponds to the upstream tag, commit ID, or filename. Registry versions may need a rev or url mapping. Do not edit the version in the Pins File to work around configuration problems.

Confirm that your Nixpkgs provides the Fetcher, especially fetchFromHuggingFace. Large models, submodules, and restricted repositories also need sufficient storage, connectivity, and credentials.

Dependency hashing fails

Check the Package's root and lockfile location. npm requires package-lock.json. pnpm requires a compatible pnpm-lock.yaml, an explicit fetcherVersion, and the same pnpm version used downstream.

Prefetching dependencies executes the intermediate FOD's build steps. A failure does not necessarily mean the final application's build is broken. Inspect the Source, Package, and dependency Hash identified in the output, then update only the affected Pin.

Reader fails

Confirm that the Pins File uses schema v2 and that you access pins.<pin>.sources.<source>.src. Supply config when you need packages or patched sources. After changing configuration, update the Pins File to keep declarations and locked results consistent.

Concurrent runs and cancellation

A write-lock conflict means another process is updating the same Pins File. Wait for it to finish before retrying; do not bypass the lock while a writer is active. Cancellation does not write results from the current run, and the existing Pins File remains usable.

If downloads and builds exhaust local resources, reduce download_jobs and hash_jobs. Interactive TUI and CI text output differ. Use exit codes, error text, and the Pins File to determine the outcome.