Passante A Passante publication

En Passante

In Passing
Field Kit

The dependency was already committed as a tarball

A registry error names the path that failed, not everything the repository already holds.

What happened

On 2026-09-02, a blocked package registry failed a dependency install and stalled a test suite, until the required package turned out to be committed in the repository as a tarball and was placed by hand to finish the install.

2026-09-02 any package manager · a proxy-blocked registry measured: none recorded
3 prompts, in order
  1. Separate a block from a bad request An install fails behind a VPN or proxy and you want to know what actually failed.
  2. Inventory archives already in the tree The verdict says the registry path is blocked and you need a local copy.
  3. Install from the archive and prove it A local archive matches the requirement and you need the install to come from it.

1Separate a block from a bad request

Run it when
An install fails behind a VPN or proxy and you want to know what actually failed.
It asks you for
The exact failing command and its complete raw output. Also the required package and version.
You get back
The first failure quoted. A failure class with its supporting line. A verdict on absent versus unreachable.
It refuses if
You paste a summary instead of the real output. The output shows a bare timeout with no host or package name.
copy this into a model
<stance>

The installer output is the only evidence in front of you right now. A proxy refusal and a nonexistent version can end the run the same way, in red. Work as a dependency triage engineer. The quick read calls every failed fetch an outage and stops work until the network changes. That read misses the case where the package already sits in the tree. Keep classification separate from fixing.

</stance>

<inputs>

Ask for these and wait for each answer. Do not guess a value.
1. The exact command that failed, copied as typed.
2. The complete output of that command, including the lines before the final error.
3. The package name and the version the install needs.
4. Whether a VPN or a proxy is active on this machine.
Stop if item 2 arrives as a summary. Ask again for the raw text.

</inputs>

<method>

1. Read the output and find the first failure, not the last. Record it.
2. Classify that failure. Choose one: network reachability, authentication, proxy or TLS interception, name or version resolution, or local disk state.
3. Quote the single line that supports your classification. If no line supports it, say so.
4. Check whether the failure names a host or a URL. A named host points at reachability or interception.
5. Check whether the failure names a version or a missing manifest entry. That points at resolution instead.
6. If the evidence supports two classes, report both. Do not pick the convenient one.
7. State plainly whether the dependency is unavailable everywhere or unavailable only over the network. That difference decides the next step.
8. Do not propose a fix in this pass. The classification is the deliverable.

</method>

<deliver>

- First failure, quoted verbatim.
- Classification, with the supporting line.
- Competing classification, if the output allows one.
- Verdict: blocked path, or absent dependency.
- The one piece of evidence that would settle an open case.

</deliver>

<refuse>

Refuse to classify from a paraphrase. Ask for the raw output.
Do not assert that the registry is down. The output shows only that one client failed to reach it.
Do not recommend disabling certificate verification. Do not recommend a mirror in this pass.
If the output shows a generic timeout with no host and no package name, stop. Say the evidence does not separate a block from a resolution failure. Name what to capture next.
Never state that the dependency cannot be installed. That claim needs a search of the repository, which is a separate step.

</refuse>

2Inventory archives already in the tree

Run it when
The verdict says the registry path is blocked and you need a local copy.
It asks you for
The repository root, the required package name, and the exact version the manifest demands.
You get back
A list of every archive and vendor directory in the tree. A candidate table with declared name, declared version and a match verdict.
It refuses if
An archive's internal metadata is unreadable, or the only match is a filename with no version evidence inside.
copy this into a model
<stance>

Repositories carry more than source. Vendored archives, offline caches and third party folders outlive the decision that added them, and the lockfile rarely explains them. Work as an engineer who inventories what the tree already contains before asking the network for anything. A filename that looks like the package is not proof of the package. The metadata inside the archive is the proof.

</stance>

<inputs>

Ask for these and wait. Do not substitute a guess for a missing answer.
1. The repository root path.
2. The required package name and the exact version constraint, copied from the manifest or lockfile.
3. Whether the network is still blocked right now.
4. The failure class from the triage pass.
If item 2 is approximate, stop and ask for the literal constraint.

</inputs>

<method>

1. List every archive file under the repository root. Include .tgz, .tar.gz, .zip and .whl. Report full paths.
2. List every directory whose name suggests vendoring: vendor, vendored, third_party, offline, cache, deps, packages.
3. For each candidate archive, read the metadata file inside it. Report the declared name and the declared version.
4. Compare each declared version against the requirement. Mark exact match, compatible, or mismatch.
5. If nothing matches, check version control history for an archive that existed earlier. Report whether one did.
6. Record the file size and a checksum for every matching archive. State that the checksum is unverified unless the repository also commits an expected value.
7. If no candidate exists, say so in one line. Do not improvise a download.
8. Treat every archive as untrusted input. Extract into a new empty directory. Do not run anything found inside it.

</method>

<deliver>

- Archive inventory with full paths.
- Vendor directory inventory.
- Candidate table: path, declared name, declared version, match verdict.
- Provenance note: checksum, and whether the repository states an expected value.
- One line answer: a usable local copy exists, or it does not.

</deliver>

<refuse>

Do not report a match on filename alone. Read the metadata first.
Do not fetch anything from the network during this pass.
If an archive's metadata is missing or unreadable, say so. Do not infer the version from the filename.
If the declared version does not satisfy the constraint, stop. Report the mismatch. Do not suggest loosening the constraint to make it fit.
If the search finds nothing, state that plainly. Do not pad the report with directories that hold no archives.

</refuse>

3Install from the archive and prove it

Run it when
A local archive matches the requirement and you need the install to come from it.
It asks you for
The archive path, the failing test command, and confirmation that the registry stays unreachable.
You get back
A before and after record, the install output line naming the local path, a version comparison, and a durability verdict.
It refuses if
The install only succeeds once the registry is reachable, or no output line names the local archive.
copy this into a model
<stance>

Install from the local file and prove the registry stayed out of it. An install that succeeds because the proxy recovered says nothing about the archive. The task here is to make the source of the package observable, then to re-run the thing that failed. Provenance is the deliverable. A green suite on its own does not show where the bytes came from.

</stance>

<inputs>

Ask for these and wait for each one.
1. The path to the matching archive and its declared version.
2. The exact command that failed earlier.
3. How the dependency is declared, manifest entry or lockfile entry.
4. Whether you can keep the registry unreachable on purpose during this run.
If item 4 is no, stop and say the proof is unavailable.

</inputs>

<method>

1. Record the before state. Run the failing command. Capture the error text.
2. Point the dependency at the local archive path. Edit the manifest, or place the file where the package manager looks for it.
3. Run the install with the registry still unreachable. Keep the block in place.
4. Read the install output. Confirm it names the local path. Confirm it names no remote host for this package.
5. Compare the installed package's declared version against the archive's declared version. Report both.
6. Re-run the previously failing command. Record pass or fail verbatim.
7. Inspect what changed in the working tree. Report whether the manifest or lockfile now records a local path.
8. State whether this is a durable configuration or a machine-local workaround. Name the files a teammate also needs.
9. If transitive dependencies still need the network, say so and list them.

</method>

<deliver>

- Before: command and error.
- Change made: file and line.
- Install output line naming the archive.
- Version check: archive declares one value, installed package declares another.
- After: command and result.
- Durability: committed path, or local only.
- Open risks: unverified checksum, version drift, unfetched transitive dependencies.

</deliver>

<refuse>

Do not report success if the registry was reachable during the install.
Do not hand-edit a lockfile to make two versions agree.
Do not loosen a constraint to accept a mismatched archive.
If you cannot show an output line naming the local path, stop. Report the install source as unconfirmed.
If the failing command still fails, do not call the archive wrong. Report the new error and classify it separately.

</refuse>
How you know it worked

Keep the registry unreachable and run the install again. Read the install output. One line names the local archive path and no remote host for that package. Then run the previously failing test command and record the result.

from a real incident, 2026-09-02 · stack any package manager · a proxy-blocked registry · verified by none recorded · dependenciesoffline-installvendoringprovenance

← every Field Kit