SecureChain Beta

User guide

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 #

ErrorCauseWhat to do
CLI exit 3 no portal tokenThe 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 tokenThe token is wrong, revoked, expired, or belongs to another workspace. A CI token of one repository also stops when the person who made it loses the member role on that repository.Check the CI secret. Make a new token.
The scans of a repository go to the wrong workspaceThe CLI has a sign-in to more than one workspace, and this repository uses another one.Read the line that starts with workspace: in the output of the scan. In the repository, run securechain auth use workspace, or set the key tenant in .securechain.yaml. A CLI before 0.1.46 keeps one sign-in only: upgrade it. See More than one workspace.
CLI exit 3 this machine has a login to more than one workspaceThe command ran without a terminal, and this repository has no workspace yet.Run securechain auth use workspace in the repository, or set --tenant.
auth login exit 2 or 3 in CI the browser sign-in does not run in CIThe browser sign-in does not run in a CI job: nobody is there to sign in, and the job would wait until its time limit. A job whose standard input is a terminal stops with exit 2. A job with no terminal, which is the usual case, stops with exit 3. The portal gets no request.Set SECURECHAIN_PORTAL_TOKEN in the job to a token from the Access tokens page, or pipe the token to securechain auth login --with-token. See In CI/CD.
auth login with no terminal prints a link and a code, and waitsStandard input is not a terminal and is empty, for example docker run with no -i and no -t. The CLI opens no browser. It prints the sign-in link and the code, and waits for the sign-in. An older CLI stops with exit 3 and the browser sign-in needs a terminal.Open the link in a browser on any device, check that the page shows the same code, and approve. The CLI then continues by itself. With docker run -i and no -t, standard input stays open, and the CLI waits for a token on it. When nothing comes within 2 seconds, the CLI prints securechain waits for the portal token on standard input, and nothing came yet. Pipe the token to standard input. For the browser sign-in, close standard input (Ctrl-D in a Unix terminal), or run docker with no -i., and goes on waiting. A token that you pipe in later still signs you in. For the browser sign-in, press Ctrl-D in a Unix terminal: standard input ends, and the CLI prints the link and the code. You can also run the command with no -i, or close standard input (< /dev/null). Do not enter the token by hand there: the terminal shows it on the screen. CLI 0.1.79 prints no line and waits with no message: press Ctrl-D, or run it with no -i. In a script, set SECURECHAIN_PORTAL_TOKEN, or pipe the token to securechain auth login --with-token. With an older CLI, upgrade it, or run the command in a terminal, for example with docker run -it or ssh -t.
auth login exit 3 the login was denied, or the code expiredSomebody 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 token (one repository) preset, 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 token (one repository) for the CLI.
403 this token is scoped to one repositoryA repository token asked for another repository.Use the token of that repository, or check the repository URL that the CLI sends.
CLI exit 2 the portal token is scoped to the repository …, and the command sent the repository …A CI token of one repository runs in another repository, for example a fork, or a project that copied the CI secret. The portal matches the URL exactly, so the same repository with another spelling (.git at the end) also stops. Nothing was stored. A CLI before this change exits 4 with repo_url does not name this token's repo.Make a CI token for this repository and put it in its CI secret. If the token's repository is this project, set submit.remote_repo_url in .securechain.yaml to the URL that the message names for the token.
403 this action needs the member roleYour 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 componentsThe 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 branchThe 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.
Warning git is not installed, so securechain listed the project's files with a directory walkThe image of the job has no git. The scan goes on, with two differences. The directory walk does not apply the .gitignore of the project, so it can read files that git ignores. The scan does not record the path of the project in the repository, so the portal cannot tell two projects of one repository (a monorepo) apart. In CI, the repository URL, the branch, and the commit still come from the CI variables.Install git in the image, for example with apt-get install git, apk add git, or dnf install git.
A finding on pip, setuptools, or wheel whose WHERE is the environment, for example /usr/local (environment tooling) or .venv (environment tooling)The package came with the Python image or with the virtual environment, and no file of the project declares it. In a conda environment, conda can show the same way. A line under the table names the environment and its packages. The finding is a real vulnerability in the image that runs the project, so it still counts for --fail-on.Upgrade the environment, not requirements.txt. Use a newer base image, or run python -m pip install --upgrade pip in the environment, with each package that the line names. For a virtual environment, run python -m venv --upgrade-deps environment. For a conda environment, run conda update -p environment packages.
--fail-on high could not fail this build: the advisory match is incompleteThe CLI cannot show that every package of the scan was checked, so the result is not clean. The CLI could not read all the findings of the portal, or could not place them on the packages of the report, the portal has no advisory source for a package type of the project (the report lists those packages under NOT ANALYSED), or the match did not end. A message this scan is incomplete means that the match is complete, but the CLI could not read, match, or apply a part of the project: each refusal of the report names that part. From CLI 0.1.86, such a scan under sca --fail-on or sca --fail-on-exploited fails the job: see the next two rows.Read the vulnerabilities section of the output: it tells you why. Fix the cause, and run the command again. A complete scan with no finding prints clean: N packages checked, no finding at or above high and exits 0. A CLI of version 0.1.74 or earlier can print could not fail this build: no vulnerability finding in this report has a severity for a clean scan too.
CLI exit 5 or 2 --fail-on level: no finding reached the bar, but securechain did not read N part(s) of this project, so this build does not passNo finding reached the level of --fail-on, and the scan did not read a part of the project (CLI 0.1.86 or later). Exit 5: you can fix each part, and the message names the fix of each one, for example a lockfile that does not parse. Exit 2: each part is a gap of securechain, for example a file that securechain does not support.Exit 5: do the fix that the message names, and run the job again. Exit 2: report it to TuxCare support. To keep exit 0 until 2027-12-01, give --accept-unread all, or set accept_unread: all in .securechain.yaml. See A part of the project that the run did not read.
CLI exit 5 or 2 --fail-on-exploited: no finding that can fail this build is known exploited, but securechain did not read N part(s) of this project, so this build does not passThe same, for sca --fail-on-exploited with no --fail-on (CLI 0.1.86 or later). CLI 0.1.82 to 0.1.85 printed a warning and exited 0. Exit 5: the message names the fix of each part. Exit 2: each part is a gap of securechain.The same as in the row above.
Warning --accept-unread all is deprecated, and is removed on 2027-12-01The run used --accept-unread all, or the key accept_unread: all. The warning goes on: It keeps exit 0 of --fail-on and --fail-on-exploited over a part of the project that securechain did not read. Each run that uses it prints the warning, whatever it read.Fix each part that a refusal of the report names. Then remove --accept-unread all, and the key accept_unread: all of .securechain.yaml, before 2027-12-01.
CLI exit 4The portal did not answer in time, the CLI is older than the portal accepts, or the portal blocks this version of the CLI (CLI 0.1.86 or later).Run the job again. If the message tells you to upgrade, see Upgrade the CLI. For a blocked version, the message gives the reason, the version to use, and the command that pins it: do what it says.
202 on findingsThe portal is still matching the scan.Wait some seconds and read again. The CLI does this for you.
429A 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.

ErrorCauseWhat to do
CLI exit 3 the portal holds no registry credential for this tenantThe workspace has no registry token.Ask an admin to save it under Settings › Registry token.
CLI exit 4 the portal … does not support /securechain/v1/registry-credential after auth login or registry loginThe setting Use the TuxCare registry is off for the workspace or the repository, and the CLI does not know the setting yet. After auth login, the sign-in is saved. The CLI wrote no registry and no token into the files of your package managers.If your builds use only your own package repositories, nothing is wrong. Else ask an admin to turn the setting on for the workspace, or a member or an admin of the repository to turn it on for the repository: see Use the TuxCare registry.
E401 from the package manager during an installThe 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.
After auth login, pip, npm, or another package manager installs from the TuxCare registry, and you did not expect itThe setting Use the TuxCare registry is on, so auth login wrote the registry into the configuration files of the package managers in your home directory, for example pip.conf and ~/.netrc. The output of auth login lists these files. With CLI 0.1.69 or later, the first line of each file names securechain and the command that removes the lines.Run securechain auth logout: it removes the registry lines, and it signs the computer out. If your builds use only your own package repositories, ask an admin or a member of the repository to turn the setting off before you sign in again: see Use the TuxCare registry. See The files that auth login and registry login write.
ETARGET No matching version found for a version that ends in -tuxcare.NA 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.
Bun name@range failed to resolve, after No version matching for a version that ends in -tuxcare.NThe overrides or resolutions block of package.json is not the block that bun.lock recorded: someone added or changed a key. Bun then resolves every override again, and the registry of the project, /npm-upstream/, has no TuxCare builds. securechain check reports this as bun-lockfile-overrides, for most forms of key.Run BUN_CONFIG_REGISTRY=https://registry host/npm/ bun install once, then commit bun.lock. The registry host is in the registry: line of .securechain.yaml. See the rule for Bun in the rules.
EINTEGRITY from npmThe 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 registryThe 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 projectMaven and Gradle need a BOM file from TuxCare.Contact TuxCare.
CLI exit 6harden, update, unharden, or fix 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.

The line flags names each rollout flag of the build, on or off, and what set it: portal (your portal sent the value) or default (the default of the build). When the portal sent no flags, the line says so. A flag is not a check: it does not change the result of doctor (CLI 0.1.86 or later).

--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:

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