Troubleshooting

What the common errors of the CLI and the portal mean, what to do about each, and how to get help from TuxCare.

Common errors #

Error	Cause	What to do
CLI exit 3 no portal token	The CLI found no token.	On your computer, run `securechain auth login`. In CI, set `SECURECHAIN_PORTAL_TOKEN` and check that the job can read it. GitLab gives a protected variable to protected branches only. GitHub gives no secret to a pull request from a fork.
401 unknown or revoked token	The token is wrong, revoked, expired, or belongs to another workspace.	Check the CI secret. Make a new token.
`auth login` exit 2 in CI	The browser login does not run in a CI job.	Set `SECURECHAIN_PORTAL_TOKEN` in the job. See In CI/CD.
`auth login` exit 3 the login was denied, or the code expired	Somebody selected Deny, the workspace refused the login, or nobody approved in time.	Run `securechain auth login` again and approve in the browser. A viewer can sign in, but cannot send scans.
403 this token cannot submit (or read, write)	The token does not have the permission, or the role of its user does not have it. A token of a viewer cannot send scans.	Make a token with the CI upload rights, or ask an admin to change your role.
403 this token cannot use the cli channel (or api, mcp)	The token does not have that channel in its rights.	Make a token with a preset for that channel, for example CI upload for the CLI.
403 this token is scoped to one repository	A repository token asked for another repository.	Use the token of that repository, or check the repository URL that the CLI sends.
403 this action needs the member role	Your role cannot make this change.	Ask an admin to change your role.
403 API access is off for this workspace (or MCP)	An admin has not turned the channel on.	Ask an admin to turn it on.
400 with zero components	The CLI found no packages to send.	Run the CLI in the project root, or use `--dir`. Check that the lockfile exists and is committed.
The scan has no branch	The CLI ran on a detached HEAD outside a CI system that it knows.	Check out the branch before the scan, for example `git checkout -B main`.
CLI exit 4	The portal did not answer in time, or the CLI is older than the portal accepts.	Run the job again. If the message tells you to upgrade, see Upgrade the CLI.
202 on findings	The portal is still matching the scan.	Wait some seconds and read again. The CLI does this for you.
429	A limit or the rate limit.	Read the `quota` field and the `Retry-After` header.

Exit codes lists what each exit code of the CLI means.

Errors with TuxCare builds #

These errors come from the CLI or from your package manager, in a project that uses TuxCare builds.

Error	Cause	What to do
CLI exit 3 the portal holds no registry credential for this tenant	The workspace has no registry token.	Ask an admin to save it under Settings › Registry token.
`E401` from the package manager during an install	The package manager has no credential for the TuxCare registry.	On your computer, run `securechain registry login`. In CI, get the credential before the install step: see TuxCare builds in CI.
`ETARGET` No matching version found for a version that ends in `-tuxcare.N`	A tool looked for a TuxCare build among the public packages. `npm update` does this, and so does an install with no lockfile.	Commit the lockfile and install from it. Move the builds with `securechain update`. See the rules.
`EINTEGRITY` from npm	The lockfile has the hash of the public package for an address that now serves a TuxCare build. A project that a CLI before 0.1.16 set up can have this.	Run `securechain init`, then `securechain harden`, and commit the lockfile. See the two paths of the registry.
`harden` exit 2, with a message that names another registry	The package manager of the project does not use the TuxCare registry.	Run `securechain init`, commit the files, and run `harden` again.
`harden` exit 4 on a Java project	Maven and Gradle need a BOM file from TuxCare.	Contact TuxCare.
CLI exit 6	`harden`, `update`, or `unharden` changed the project, but the installed packages are not the planned ones. The CLI put your files back.	Read the message: it names the package. Contact TuxCare if it stays.

Diagnose your setup: doctor #

securechain doctor
securechain doctor --bundle support.tar.gz

doctor checks the environment of the CLI: the package managers and their versions, the configuration files, the connection to the portal, and the proxy and CA settings. It prints what it finds and changes nothing.

--bundle also writes a support archive. The archive has the same facts and the trace of the last command. The CLI removes each token from it. Attach the archive when you contact TuxCare.

Get help #

If this guide does not answer your question, contact TuxCare. Give these facts:

The address of your workspace.
For a scan, the scan number from the Scans tab of the repository page.
The output of securechain version, and the archive of securechain doctor --bundle.

To report a vulnerability in SecureChain itself, use vulnerability reporting.