Registry, auth, and network

Three failures

Match the message to the failure, then run the next command.

Examples use placeholders (<token>, <key_id>, <secret>, <file>, <host>, <path>). They are not real values.

A DSN, an npm token, an Authorization header, and a URL that contains a username and password are credentials. They must not appear in vg output or in CI logs. vg removes those shapes from registry and upload errors before it prints them. If a log already contains one, rotate it. In CI, set VIBGRATE_DSN in the secret store. --dsn puts the value in the process list. vg dsn create prints the new DSN once so you can store it. That line is the secret. Do not run vg dsn create in a job whose log is kept.

Runtime errors are prefixed with error: and a line (ref <id>). The id is a correlation id for that process, not a credential.

Offline scan

vg scan --offline does not call a package registry, does not call OSV, and does not upload, even when a DSN is set. The npm registry banner below is not printed.

Without --package-manifest, latest versions are not looked up. Dependency drift for those packages is unknown. A missing latest version is not a score of zero.

vg scan --offline --package-manifest <file>

<file> is JSON, or a ZIP that contains package-versions.json, manifest.json, or index.json. One published bundle is https://github.com/vibgrate/manifests/latest-packages.zip.

A bad manifest stops the command (exit code 1) before the scan:

npm registry check

An online vg scan checks https://registry.npmjs.org/npm/latest before it scores.

• A network failure (no response: DNS, timeout, connection refused) falls back to npm view npm dist-tags.latest, which uses your .npmrc.
• An HTTP response that is not OK, including 401 and 403, fails the check immediately. That path does not fall back to npm view, and it does not send your npm token.

Either failure stops the scan (exit code 1) with this banner:

✖ Vibgrate cannot connect to the npm registry to check package versions.

  Possible causes:
  • No internet connection
  • Corporate proxy/firewall blocking registry.npmjs.org
  • npm is not installed or not in PATH

  Try running: npm view npm dist-tags.latest

The process also prints error: and (ref <id>) — re-run with --json for detail, or report at https://vibgrate.com/help.

Next step:

1. Run npm view npm dist-tags.latest.
2. If that command cannot resolve a host or times out, you are offline or blocked. Download a package-version manifest and run vg scan --offline --package-manifest <file>.
3. If npm says it is not authorized (HTTP 401 or 403), the registry answered and your npm config is wrong. Fix the registry in .npmrc, or sign in with your package manager.
4. If npm view succeeds and vg still prints the banner, registry.npmjs.org returned a non-OK status, so the npm fallback did not run. Allow that host, or use the offline manifest.

PyPI, NuGet, Maven Central, RubyGems, crates.io, the Go module proxy, Packagist, pub.dev, Hex, Docker Hub, Artifact Hub, and the Terraform Registry do not print this banner. A failed lookup leaves that package's drift as unknown.

npm view stderr is not printed on this banner. If a later error keeps that stderr and it contains a token, an authorization header, or a URL with a password, that text is removed before it is shown.

vg update uses a separate check. When that check returns nothing, it prints this and exits 1:

Could not reach the npm registry. Check your network connection.

Confirm npm view npm dist-tags.latest, then re-run vg update.

Vulnerability feed

vg scan --vulns queries OSV. When a batch cannot be completed, the vulnerability step says:

OSV unreachable — not checked

That line means the feed was not reached. It does not mean the tree has no vulnerabilities. The command still exits 0 unless another gate fails.

vg scan --vulns --offline does not contact OSV. Advisories come from --package-manifest. When that file has no matching advisories, the step says none found.

Upload authentication

vg scan uploads when you pass --push, or when a DSN is already available, unless you passed --offline. DSN resolution order:

1. --dsn <dsn>
2. VIBGRATE_DSN
3. The VIBGRATE_CREDENTIALS file, if set; otherwise <project>/.vibgrate/credentials.json when that file exists; otherwise ~/.vibgrate/credentials.json

No DSN, from vg scan --push (and from a scan that expected to upload), prints:

No DSN provided for push.

A following line tells you to sign in, set VIBGRATE_DSN, or pass --dsn. Run vg login, or set VIBGRATE_DSN. A claim link is also printed: https://dash.vibgrate.com/claim?vid=<id>&job=scan_drift&channel=cli. It identifies this install. It is not a DSN.

vg push prints No DSN provided. and the same hints. With --strict, the command exits 1. Without --strict, the local result is kept and nothing is uploaded.

Invalid DSN:

Invalid DSN format.

vg push also prints:

Expected: vibgrate+https://<key_id>:<secret>@<host>/<workspace_id>

vg scan --push does not print the expected format. Next step: vg login, or replace VIBGRATE_DSN. Do not print the old value.

When the upload request fails:

Upload failed: HTTP <status>: <body>

A network error uses the same Upload failed: prefix and the client error text. Tokens, authorization headers, and credential-bearing URLs are removed from <body> and from that client text. HTTP 401 or 403 means the DSN was rejected. Next step: vg login, or check VIBGRATE_DSN (key, secret, host, and workspace). With --strict, exit code is 1. Without it, the local scan result remains.

Before an upload, scan calls preflight. A transport or HTTP failure prints:

Preflight check failed: <message>

<message> is HTTP <status>: <body> or the client error, with the same redaction. Without --strict, the scan continues. With --strict, the command exits 1 before the scan.

A plan limit is a separate warning. It names the limit (repository cap, scan credits, or VM minutes), says results will not be uploaded, and the local scan still runs.

vg login network failures:

Failed to start login (HTTP <status>).
Could not reach <host>: <message>

<host> is the ingest host (us.ingest.vibgrate.com or eu.ingest.vibgrate.com, or the host of --ingest). Next step: check the network, then retry vg login. --region selects us or eu. An unknown region prints Unknown region "<id>". Supported: us, eu. A region that is not live yet prints Region "<id>" (<label>) is not yet available. Supported: us, eu. A bad --ingest value prints Invalid ingest URL: <input> with credentials removed from <input>.

If the browser denies the request, the line is ✖ Login was denied in the browser. Next step: vg login.

If the request expires or the wait times out, the message says so and tells you to sign in again. Next step: vg login.

Signed in, workspace not created:

✖ Signed in, but workspace setup failed: Failed to provision workspace: <error>

A following line tells you to finish setup with vg dsn create --workspace new. That command prints Failed to provision DSN: <error> when the provision call fails. <error> is the server text or HTTP <status>, with credentials removed. Next step: confirm the ingest host, then retry.

Build and module install

vg build fetches the Architecture module when it is missing, unless you passed --offline or --local. When the registry cannot provide it, and the output is not --json or --quiet, build prints:

architecture module could not be installed — role/purpose lines are omitted; vg retries automatically (disable with VIBGRATE_NO_KERNEL=1)

The build still finishes. Role and purpose lines are omitted. --offline skips the fetch and does not print this line.

vg module install <name> (names: relevance, hcs, arch):

install failed: <detail> — check network access to the registry, or retry later

Exit code 1. <detail> is one of registry <status> (for example registry 401 or registry 403), tarball <status>, no published version, or an integrity message (integrity mismatch (sha512), integrity mismatch (shasum), malformed integrity metadata, registry provided no integrity metadata). HTTP 401 or 403 means the registry refused the request. A thrown fetch error is <detail> as well, cut at 200 characters, with credentials removed.

vg update, after the CLI itself is current, prints a module line when a refresh fails:

<package> module could not be updated — registry unreachable or no published version

registry <status> or tarball <status> appears in that same position when the registry answered. The CLI update itself still succeeds. Next step: restore registry access, then vg update or vg module install <name>.

vg install --login with --offline or --local exits 5:

--login needs the network; it cannot run under --local/--offline

Next step: run vg install without --login while you are offline, or drop --offline / --local when you want the device login.