Troubleshooting by symptom
Start from what you see, and find the fix
Something did not work, and you want it working again. This chapter is organised by what you see: find the message or the behaviour that matches yours, read why it happens, and run the fix. Every message here is real output from Gritpack 1.2.63. Start with the two general tools below; they solve or explain most problems on their own.
What you will be able to do
- Use
gritpack doctorand JSON errors to find the cause of a problem. - Recognise the common failures when installing, logging in, getting packages and publishing, and fix each one.
- Know when the fix is yours and when to ask your hub's administrator.
First: two general tools
gritpack doctor
Run gritpack doctor in the project directory. It checks, in order, the
project, your login profile, where its credential is kept, your account, the
hub, the project's manifest, lock file and installed packages, and the
ecosystem's own settings. Each line passes or fails, and each failure says
what to run:
$ gritpack doctor
PASS project — detected native at ./app
PASS profile — profile=default provider=file
PASS provider — credential material resolved
PASS identity — account=01a1e865-dd2b-7f10-9340-1658dbafa174 email=ada@example.com status=Active
PASS hub — repository=550e8400-e29b-41d4-a716-446655440000 endpoint=https://packages.example.com:443
PASS local — workspace: workspace directory exists
PASS local — manifest: 1 direct dependencies
PASS local — lock: lock v4 with 1 packages
FAIL local — installed-universe: installed file is stale or missing: ./packages/@ada/textkit/LICENSE
repair: gritpack sync
FAIL local — consistency: installed file is stale or missing: ./packages/@ada/textkit/LICENSE
repair: gritpack sync
...
doctor found unhealthy project state
The first failure is usually the one to fix; later ones often follow from it.
gritpack doctor --fix first runs gritpack setup for the project (the
reversible, local part: routing Cargo, npm or Go to your hub), then checks.
It never logs in, publishes or changes anything on the hub. doctor exits
with status 7 when anything fails, and --json gives the same checks as
data.
See the whole error
A human error shows one line. The underlying causes are often more useful,
and --error-format json shows them:
$ gritpack login ada@example.com --hub packages.example.com --code ... --store file
enrollment request failed: error sending request for url (https://packages.example.com/v1/enrollments)
$ gritpack login ada@example.com --hub packages.example.com --code ... --store file --error-format json
{"schema":"gritpack/error@1","code":"GRITPACK_UNAVAILABLE","category":"unavailable","exit_code":8,"message":"enrollment request failed: ...","causes":["error sending request for url (...)","client error (Connect)","invalid peer certificate: UnknownIssuer"]}
The last cause, invalid peer certificate: UnknownIssuer, is the real
reason. The exit code also tells you the kind of problem at a glance:
2 usage, 3 authentication, 4 authorization, 5 not found, 6 conflict,
7 integrity, 8 unavailable, 9 local files. Scripting with
JSON has the full table.
Installing and running Gritpack
gritpack: command not found after installing
The installer puts commands in ~/.frogfish/gritpack/bin and offers to add
that directory to your shell's login profile. A terminal that was already
open does not see the change. Open a new terminal. If it still fails, add the
directory yourself (~/.zprofile, ~/.bash_profile or ~/.profile):
export PATH="$HOME/.frogfish/gritpack/bin:$PATH"
On Windows, open a new PowerShell window after installing.
An application you installed is "not found"
Same cause: gritpack install puts the application's commands in
~/.frogfish/gritpack/bin, and it does not edit PATH itself. Check what
Gritpack installed, and where the command points:
$ gritpack app list
@frogfish/scroll-throttle 1.0.0 provenance=registry-recorded origin=https://get.gritpack.org:443 commands=scroll-throttle
$ gritpack app which scroll-throttle
scroll-throttle -> @frogfish/scroll-throttle 1.0.0 (https://get.gritpack.org:443)
If app which knows the command, the fix is PATH. See
Installing applications.
The wrong Gritpack runs
gritpack version shows the version and the path of the executable that ran.
If it is not the one you expected, another copy is earlier on PATH. Remove
it, or put ~/.frogfish/gritpack/bin first.
A command prints a note about a new name
$ gritpack whoami
note: `gritpack whoami` is now `gritpack auth status`; the old name stops working in 1.4.0.
The old name still works. Use the new one in scripts and notes; old names stop working in 1.4.0.
Logging in
profile configuration does not exist: ~/.frogfish/gritpack/config.toml
You have not logged in on this machine (or GRITPACK_HOME points somewhere
new). Exit 2. Log in: gritpack login, or for a private hub
gritpack login you@example.com --hub <hub> --code <code>. See
Logging in.
invalid profile configuration: profile "work" does not exist
--profile or GRITPACK_PROFILE names a profile you do not have. Exit 2.
gritpack auth list shows the ones you do have.
enrollment server returned HTTP 401: invalid enrollment proof
The hub refused the code. Exit 3. The code was mistyped, already used, older than 24 hours, revoked, or given with a different email than the one it was issued for. The hub deliberately does not say which. Check the email, then ask the administrator for a new invitation.
invalid peer certificate: UnknownIssuer (in the causes)
Gritpack does not trust the certificate the hub presented. Exit 8. The
public hub uses an ordinary web certificate; a private hub may use its own
certificate authority. Pass the CA file your administrator gave you with
--ca the first time you log in. login saves it with your credential, so
later commands do not need it.
error sending request ... Connection refused or a timeout
The hub could not be reached at all. Exit 8: try again, and check the
address (--hub), your network, VPN and proxy. Exit 8 is the one failure
that may go away on its own.
A warning that your login expires soon
From a week before a login's 30 days run out, every command that uses it
prints a warning on standard error: it names the credential, the date it
expires and how long is left, and says to renew it with an invitation from
the hub's operator and gritpack auth renew. Ask your administrator for a
code, then:
gritpack auth renew --hub <hub> --code <code>
"this Gritpack login ... expired"
An expired login cannot renew itself. The message says so and points you to
gritpack login. Ask for an invitation and log in again with the same
--profile name, so your settings that name the profile keep working.
Permission refused
the hub answered HTTP 403: credential is not authorized
Exit 4. The hub knows who you are, but will not let you do this. The usual reasons:
- Your account is suspended. Then every command fails this way, even
gritpack auth status. Ask your administrator. - You acted on something you do not own, for example yanking a version
in someone else's scope. Check
gritpack auth status: itswritable_scope=lines list the scopes you may publish in.
PUBLICATION_AUTHORITY_DENIED: account does not own package scope
publish (or its dry run) found that you do not own the package's scope.
Exit 6. Publish under a scope you own, claim the scope if nobody owns it
(gritpack scope claim <name>), or ask the administrator to assign it. See
Names, scopes and owners.
Getting packages
package X was not found or cannot resolve X: root requires X *
Exit 5. Gritpack asked the hubs your logins configure and none of them has a package by that name that you may use. Check:
- The name. Scoped names need their scope:
@ada/textkit, nottextkit.gritpack search textkitfinds the exact name. - The hub. With a private login, Gritpack asks your private hub first and
the public hub only when the private one says "not found". To look at only
one hub, add
--from get.gritpack.org(or your hub). See Hubs and sources. - Yanked or quarantined versions. A version its publisher yanked is not chosen for new projects, and one an administrator quarantined is hidden from everyone. If every version is in one of those states, the package looks missing.
cannot resolve X: root requires X =1.0.0
You asked for an exact version that cannot be chosen, most often because it was yanked. Use a newer version. A project whose lock file already names a yanked version keeps installing it; yanking only affects new choices.
If you typed =1.0.0 unquoted in zsh and saw zsh: 1.0.0 not found, the
shell ate the =. Quote it: gritpack add @ada/textkit '=1.0.0'.
gritpack search prints nothing
Nothing matched, and that is not an error (exit 0). Try fewer words or a
different spelling, or check you are asking the hub you mean
(gritpack auth status and --hub).
locked package X is unavailable or no longer matches its requirements
sync --frozen found that gritpack.lock does not satisfy gritpack.toml,
usually because the manifest was edited and the lock was not updated. Exit 5.
On your own machine, run gritpack sync (or the add, update or upgrade
that was intended) and commit both files. In CI, this is the check doing its
job. The same message appears when an administrator has quarantined a
locked version; then the fix is theirs, or a newer version.
offline cache does not contain ...
sync --offline needs every package file in the local cache, and one is
missing; the message names the package and the file's digest. Exit 5. Run
gritpack sync once with the network to fill the cache, or import a bundle
that carries it (see Offline bundles and slices).
installed file is stale or missing: ./packages/...
verify or doctor found that a file in the packages directory was changed
or deleted. Exit 7. Do not edit files under packages/; Gritpack owns that
directory. Run:
gritpack sync
It puts back exactly what the lock file names. If you need to change a dependency's code, work on your own copy and publish a new version of it.
cache verify reports corrupt objects
$ gritpack cache verify
cache root=~/.frogfish/gritpack/cache objects=1 bytes=1282 corrupt=1 locks=0 temporary=0
...
A file in the download cache does not match its digest (a disk problem, or
something wrote into the cache). Exit 7. Gritpack checks every cached file
each time it is read, so a damaged file is never installed. The next online
gritpack sync fetches a good copy and replaces it; after that,
cache verify reports corrupt=0. An --offline sync fails on the damaged
file instead, because it cannot fetch a replacement.
Running out of disk
gritpack cache status shows the cache's size. gritpack cache prune --max-bytes 5GiB shows what would be removed to get under that size (oldest
first), and --apply removes it. --max-age-days selects by age instead.
Publishing
publication requires --yes when input is non-interactive or structured output is selected
publish wanted to ask for confirmation and could not: there was no terminal,
CI was set, or you asked for JSON. Exit 2. Add --yes once you are sure, or
run publish --dry-run first.
PUBLICATION_DOCUMENTATION_REQUIRED: ... has no README
Every new version needs a README of at least 100 words of prose and a licence
declaration. Exit 6, and nothing was uploaded. Write the README and set
readme = "README.md" and license = "..." in the manifest, or give your
reason for going without one: --without-readme "<reason>". See
README and licence.
PUBLICATION_LICENSE_NOT_ALLOWED
The hub has a licence rule that does not allow the licence your manifest declares. Exit 6. The message names the rule, the allowed licences and the term that is not allowed. Correct the licence in the manifest. Only the hub's administrator can change the rule, so if you think the rule is wrong, ask them; see Licence rules, quarantine and the audit log.
PUBLICATION_IDENTITY_CONFLICT: the immutable identity is occupied by different content
That version is already published with different content. Exit 6. A published version can never change. Raise the version number and publish again. (Publishing the very same content again is not an error: Gritpack recognises it, reports the earlier publication, and stores nothing new.)
the hub answered HTTP 409: resource already exists from scope claim
Somebody already owns that scope. Exit 6. Choose another, or ask the
administrator who owns it (gritpack admin scope view <scope>).
A publication was interrupted
If your connection dropped or the job was cancelled during publish, run the
same command again. It finishes the publication already under way instead of
starting a new one. gritpack publication status <transaction> shows where
it stands. See Publishing step by step.
Administration
administrator commands need --hub, --cert, --key, --ca
No administrator profile is chosen. Exit 2. Run gritpack admin profile list;
if it shows profiles but none marked *, choose one with
gritpack admin profile use <name>. Otherwise save one with
gritpack admin profile add. See Administering a hub.
the hub answered HTTP 400: invalid administration operation
The hub refused an administrative change as not allowed in the current state. Two common cases in 1.2.63:
admin user deleteof an account that still owns a scope. Unassign or reassign its scopes first (admin scope listshows them).- A scope written with its
@inadmin scope view. Writesamco, not@samco.
A command exits with status 141 and prints nothing
In 1.2.63 this happens when an administrator certificate is passed to a
package command (search, info and so on) with --cert and --key.
Administrator certificates work only with gritpack admin; use your login
for everything else.
Still stuck?
Collect what you have before you ask for help:
gritpack version
gritpack doctor --json
gritpack <the failing command> --error-format json
Send those to your hub's administrator, or for the public hub and Gritpack itself, to Frogfish. Leave out private keys: nothing above prints one.
What just happened
You learned to start with doctor and JSON errors, and you have a fix for
each failure people meet most: Gritpack or an application not on PATH,
login codes and certificates, permissions, packages that cannot be found or
resolved, a damaged cache or packages directory, and the checks a publication
must pass.
You can stop here
When your problem is solved, you are done. Come back to this chapter when the next one appears.
Next
If you are moving a project from another package manager, read Coming from Cargo, npm or Go. To make failures easy for scripts to handle, see Scripting with JSON.