Surveyor

Troubleshooting

Find the message spice printed, or the symptom that matches, and follow the fix. The headings quote each message without the symbol printed before it; <path> and similar stand for the value in your message.

For more detail on any run, add --log-level=debug and run it again, and add --log-file=spice.log to save a copy of the output. Messages marked JVM mode appear only when you run the CLI without Docker, in JVM mode (SPICE_LABS_CLI_USE_JVM=1). On Windows, the wrapper’s own messages use [X], [!] and [*] in place of the symbols, and a few differ slightly in wording.

Setup and Docker

Docker is not installed or not in PATH

The CLI runs in Docker by default. Install Docker from docs.docker.com/get-docker, make sure it is running, and open a new terminal. On Windows, install Docker Desktop and start it before you run spice. If you cannot use Docker, see JVM mode.

Docker on this machine runs Windows containers.

The CLI runs in a Linux container, and this machine’s Docker runs only Windows containers. In Docker Desktop, right-click the Docker icon and choose Switch to Linux containers, then run spice again. Windows Server’s Docker Engine cannot run Linux containers; use a machine whose Docker can.

Failed to pull <image>, then Image <image> not found locally either.

spice could not download the CLI image and has no local copy. Check that:

  • Your machine can reach Docker Hub, or the registry you use.
  • If you set SPICE_IMAGE or SPICE_IMAGE_TAG, that image and tag exist. A tag must be in SPICE_IMAGE itself when SPICE_IMAGE is set: see Pin the CLI version.
  • If you used --features, your machine has access to that product’s private image.

If you see Failed to pull <image> followed by Using local copy., the run continues with the image you already have.

Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro

On a machine with no network, set SPICE_LABS_CLI_SKIP_PULL=1 so the wrapper uses the image already loaded and never tries to pull it.

A newer version of this script is available. Run:

Your wrapper script is older than the latest release. Run the install command it prints, or see Install the Surveyor CLI.

The shell cannot find spice

  • Open a new terminal after installing.
  • Check that the install folder is on your PATH: ~/.local/bin on macOS and Linux, %USERPROFILE%\.spice\bin on Windows.
    Applies to:
    • Surveyor CLI
    • Surveyor IT
    See Set your PATH and Spice Pass.

Missing: <jar>

JVM mode. There is no CLI jar at the path in SPICE_LABS_CLI_JAR. Point it at your jar, or unset SPICE_LABS_CLI_USE_JVM to run in Docker.

Applies to:
  • Surveyor CLI
  • Surveyor IT

Spice Pass

SPICE_PASS must be set via SPICE_PASS env var for upload. Use --no-upload to skip upload.

An inventory or image survey needs your Spice Pass to upload. Generate one and set SPICE_PASS, or add --no-upload to survey locally. A runtime survey reports the same problem as SPICE_PASS not set, or in JVM mode as SPICE_PASS must be set for upload. Use --no-upload to run locally.

SPICE_PASS must be set (or SPICE_LICENSE, for a Spice License)

spice pass decode has nothing to decode. Set SPICE_PASS (or SPICE_LICENSE) in the same terminal and run it again.

Both SPICE_PASS and SPICE_LICENSE are set; set only one.

Unset the one you do not use. A Spice Pass uploads to a Topographer project; a Spice License unlocks a licensed edition. See Editions and licenses.

The upload fails

  • Run spice pass decode and check the Status line. If it says EXPIRED, generate a new Spice Pass.
  • Check that Project ID is the project you expect. A Spice Pass works for one project only.
  • Check that SPICE_PASS holds the whole pass, with no extra spaces or line breaks.
  • Check your network connection and that your machine can reach the Upload Server shown by spice pass decode, then run again.
Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro

Spice License

Every command except spice pass decode, spice config explain and tab completion checks the Spice License first, and stops with one of these messages when it cannot run. <product> is the product’s name and <date> a date and time in UTC. See Spice License for how to set and check one.

The <product> edition requires a Spice License.

SPICE_LICENSE is not set, or is empty, in this terminal. Set it to the Spice License issued to your organization and run again.

SPICE_LICENSE holds a Spice Pass (<type>), but the <product> edition needs a Spice License.

The variable holds a credential for uploading to a hosted project, which this product cannot use. Ask Spice Labs for a Spice License.

SPICE_LICENSE is not a Spice License: <reason>

The value is not a license at all, often because it was cut short when it was copied. Set it again from the file you received, with no extra spaces or line breaks.

SPICE_LICENSE was not signed by the key this build of <product> trusts.

The license was changed after it was issued, or was issued for a different build. Ask Spice Labs for a license for the image you run.

Your Spice License expired on <date>.

Ask Spice Labs for a new license, then set SPICE_LICENSE to it.

Your Spice License is not valid until <date>.

The license starts later than this machine’s clock reads; the next line of the message shows the clock. On an isolated machine the clock is often wrong: set it correctly and run again.

Your Spice License does not cover the <product> edition: it lacks <features>.

The license was issued for a different product. The next line lists what it covers. Run the product the license covers, or ask Spice Labs to extend it.

Your Spice License expires on <date>; contact Spice Labs for a new one before then.

A warning, not an error: the run continues. It appears on every run in the last 30 days of the license. Ask Spice Labs for a new license before the date.

This build of <product> is missing its licensing key

The image itself is faulty, which nothing you set can fix. Send the output of spice --version to Spice Labs support.

Inventory and image surveys

Input path does not exist: <path> or Input directory is empty: <path>

Check the <input> argument of spice survey inventory. Relative paths are resolved from your current folder, and a folder must contain at least one file.

Cannot use both --no-upload and --upload-only

Pick one. Use --no-upload to survey without uploading, and --upload-only to upload the results of an earlier run.

--tag-json is not valid JSON or --tag-json must be a JSON object

The value must be a JSON object such as {"env":"dev"}. On Windows PowerShell 5.1, assign the JSON to a variable first, as the message suggests. See Tag a survey with metadata.

--threads must be at least 1, got: <n>

Use a whole number of 1 or more, or leave --threads off to use half your CPU cores.

Failed to pull image (<image>), oras exited <n>:

spice could not download the image you asked it to survey. The lines after the message are the download tool’s own output. Check the image name and tag, and for a private registry run docker login <registry> first. See Survey a private image.

The survey covered fewer artifacts than expected

If you are using a trial or demo Spice Pass, it may carry an artifact cutoff. Look for Ignoring artifacts published after <date> in the output, or run spice pass decode and look for Artifact Cutoff. See Artifact cutoff.

The local results are missing

Without --output, results are written inside the CLI’s container and discarded when the run ends. Run again with --output ./spice-results and look inside spice-results/surveyor/survey-<random-id>/.

Registry sweeps

--config is required, or repositories in the host's configuration

Name your registry configuration file with --config, after registry <command>. See Registry sweeps and CBOMs.

--discovery is required for --process or --output is required for --process

spice registry cbom --process needs both: the discovery file that selects what to build, and the folder the CBOMs go to.

Discovery file not found: <path>

Run spice registry discover --output first, and run spice from the folder that holds the discovery file, or give its full path.

no action: use --process, --reset or --export-processed

spice registry cbom needs one of those three options.

No packages to process

The discovery file’s include and exclude rules select nothing. Loosen them, or run spice registry discover --output again.

All <n> package(s) already processed

Every version the discovery file selects already has its CBOM. To build them again, run spice registry cbom --reset first, or --reset --purl=<purl> for one package.

Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro

'registry run' uploads survey results to the platform, which this build does not do.

Use spice registry cbom --process to build the CBOMs on this machine.

Runtime surveys

No command specified after --

Put -- between the spice options and your command, for example spice survey runtime payments-api --jfr -- java -jar app.jar. In JVM mode the message is No command specified. Use -- to separate the command to execute.

No subject specified

Add a subject label before --, for example spice survey runtime payments-api --jfr -- mvn test.

Missing required option: '--jfr'

JVM mode. Add --jfr. Include it in every runtime survey, in Docker mode too.

No JFR recordings found in <folder>

Your command ran but produced no recordings. In JVM mode the message is No JFR recordings found. The target application may not have produced any. Check that:

  • The command starts a Java process. A script that launches Java counts.
  • The application exits normally after doing real work, so the recording is written.
  • Your command’s output shows no Flight Recorder start-up errors.

Target command exited with code <n>. Still collecting recordings.

Your command failed, for example with a failing test. The survey continues with whatever was recorded and then exits with your command’s exit code.

JDK <n> is not supported by the JFR parser. JDK 11+ is required for the CLI to parse JFR recordings.

JVM mode. Run the application on JDK 11 or later.

Could not download probe config. Using native-only mode.

Applies to:
  • Surveyor CLI
  • Surveyor IT

spice could not fetch the agent’s probe configuration, so it recorded the JDK’s built-in security events only. The download needs your Spice Pass: set SPICE_PASS, check your network connection, and run again for full detail. To skip the download on purpose, add --native-only. In JVM mode the message is Failed to download probe config. Falling back to native-only mode.

Applies to:
  • Surveyor IT Pro
  • Surveyor OT Pro

Expected on this machine: the probe configuration comes from Spice Labs, so the run records the JDK’s built-in security events only. Add --native-only to every runtime survey to skip the attempt.

No --anchor given; this survey will not correlate into a combined CBOM.

The survey still runs, but it cannot be combined with an inventory survey. Add --anchor=<path-to-jar>. See Anchor the survey to an artifact.

Total recording size exceeds 1GB. This may indicate excessive instrumentation.

JVM mode. The run was very long or recorded a lot. Survey a shorter run of the parts of the application you care about.

This image does not support runtime surveys (no JFR settings in <image>)

The CLI image you are running has no runtime survey support. Run the Surveyor CLI image, spicelabs/spice-labs-cli, or check what SPICE_IMAGE is set to.

'survey runtime' is not available in this image (<image>)

Printed by the macOS and Linux wrapper. The product you are running does not include runtime surveys. Run spice survey --help to see which surveys it has.

Configuration

No command reads [<group>] — check the spelling, or the plugin may not be installed

A group name in your configuration file is misspelled, or belongs to a plugin you do not have. The run continues without it. Fix the name and check with spice config explain.

[analysis] unknown key: <key>

A key in the [analysis] group is misspelled or not supported. See Settings for the keys.

[logging] level must be one of error, warn, info, debug, trace, got: <value>

Set level in [logging] to one of the values listed.

[logging] file was set in <source>, but it can only be given as --log-file

The log file can only be set with --log-file on the command line. Remove file from the group named in the message, or SPICE_LOGGING_FILE from your environment.

A setting is not taking effect

Run spice config explain <command>, for example spice config explain survey inventory, to see the value each setting will use and where it came from. Options beat environment variables, which beat the configuration file. In Docker mode, SPICE_<GROUP>_<KEY> variables do not reach the CLI unless you pass them through SPICE_DOCKER_FLAGS: see Which value wins.