Precheck message reference

Every failure and warning message reported by the CAST Imaging installation prechecks, what it means and how to resolve it

Overview

Available in ≥ 3.6.7-funcrel

This page lists the messages the installation prechecks report when a check does not pass, what each message means and what you need to do about it. For an explanation of what the prechecks validate, which components each group applies to and when a group is skipped, see Installation prechecks.

How to read a result line

Each result in the precheck report is a single line split into three columns by a | delimiter:

STATUS | Check name | Result detail

For example:

FAIL | Deploy folder readiness | cannot determine location (DEPLOY_FOLDER not set)
OK   | Deploy folder readiness | ready

The STATUS column tells you whether you have to act before you install:

Status Effect on the installation
OK The check passed. No action required
WARN The installation continues. Review the message and decide whether to act before or after installing
FAIL The installation does not start. Nothing on the machine has been changed, so resolve the reported condition and run the installer again

System

Check Status Result detail Meaning What to do
Supported Linux OS FAIL The detected OS identifier, ubuntu20.04 for example The release is not one of those CAST validates Install on a supported release. An untested release may work but is not certified
Supported Windows OS FAIL The detected OS caption The host is not Microsoft Windows 10/11 or Server 2016/2019/2022/2025 64bit, or it is Server Core Install on a supported edition. Server Core is not supported
CPU architecture x86_64 FAIL The detected architecture, aarch64 for example Only x86_64 is supported - CAST Imaging ships no ARM64 images Install on an x86_64 host
glibc >= 2.28 FAIL not found, or a release below 2.28 The operating system is too old for the CAST containers, RHEL/CentOS 7 for example Upgrade to an operating system providing glibc 2.28 or above
Java JDK present, Microsoft Windows FAIL Java not found (PATH or JAVA_HOME), Java version not detected, or Java <release> (need 17-25) No JDK was found, its release could not be read, or it is outside the supported range Install a supported 64bit JDK and set JAVA_HOME. A JDK is mandatory on Microsoft Windows, where CAST Imaging uses it to encrypt and decrypt passwords
Java JDK present, Linux WARN As above The same condition, but a JDK is optional on Linux A JDK is needed on Linux only to decrypt encrypted (CRYPTED2) passwords. Where you install with plain-text passwords, the warning can be disregarded

Kernel

Check Status Result detail Meaning What to do
fs.file-max >= 65536 WARN n/a, or a value below 65536 The kernel file descriptor limit could not be read, or it is too low. Neo4j and PostgreSQL both open many file descriptors Raise the limit with $ sysctl -w fs.file-max=65536 and persist it in /etc/sysctl.conf

Container engine

The Docker checks run by default on Linux. The Podman checks run in their place where you launch the installer with --engine podman.

Check Status Result detail Meaning What to do
Docker Engine >= 20.10 FAIL not found, or a release below 20.10 Docker is missing or too old Install or upgrade Docker Engine to 20.10 or above
Docker Compose v2 plugin FAIL failed docker compose version did not respond. The standalone docker-compose v1 command does not satisfy this check Install the Compose v2 plugin
Docker daemon up and usable FAIL failed docker info failed: either the daemon is not running, or the current user cannot reach it Start the daemon, then add the user to the docker group or configure rootless Docker and log in again
Podman >= 4.x FAIL not found, or a release below 4 Podman is missing or too old Install or upgrade Podman to 4.x or 5.x
Podman compose provider FAIL failed No compose provider responds behind podman compose Install podman-compose, or make docker-compose available for podman compose to use
Podman usable, rootless FAIL failed podman info failed and the rootless runtime cannot be reached Check the rootless Podman setup for the current user: the subuid and subgid mappings, and the Podman service

Required images

Reported on Linux only, once per package being installed, as Target-release images available (<package>). The result detail gives a count of the images that were found - 7/7 target images - the package it applies to, and where the list of images came from. Where no installed .env file is available to resolve them, the package defaults are used and the detail says so.

A failure means that at least one image the package will pull for the release named in configuration.conf is not available:

  • For an online installation, the image is not published on the registry. Check that the release named in configuration.conf is correct and has been published, and that the machine can reach the registry.
  • For an air-gapped installation run with --offline, the image is not present in the local image store. Transfer the missing images to the machine before installing - see the air-gapped instructions in your Linux installation guide.

Commands

Check Status Result detail Meaning What to do
Command curl present FAIL missing curl is not on the PATH. The installer uses it for HTTP health checks and downloads Install curl
Command tar present WARN missing tar is not on the PATH. It extracts image archives and bundles, which an air-gapped installation depends on Install tar
Command unzip present WARN missing unzip is not on the PATH. It extracts zip-format bundles and deliverables Install unzip
Command ss present WARN missing ss is not on the PATH. It is used to detect ports already in use Install iproute2

Network

Check Status Result detail Meaning What to do
extend.castsoftware.com reachable FAIL UNREACHABLE The CAST Extend endpoint used to download and synchronize extensions cannot be reached Check your outbound access, proxy and firewall rules for https://extend.castsoftware.com external link. Where access is not permitted, install the Extend Local Server. For an intentionally air-gapped installation, run the installer with --offline
Control Panel reachable FAIL UNREACHABLE An analysis-node, imaging-viewer, dashboards or MCP component cannot reach the Control Panel of the central machine on port 8098 Check the network path and firewall rules between this host and the Control Panel host, and that CAST_CP_URL is correct. The check is skipped where CAST_CP_URL is not set, as it is for a single machine installation
registry-1.docker.io reachable WARN UNREACHABLE Docker Hub cannot be reached to pull the container images Either resolve the outbound access, or transfer the images to the machine before you install. Expected where you run the installer with --offline

Maven

Check Status Result detail Meaning What to do
Maven Central, Jenkins releases, JBoss public or Apache snapshots reachable WARN UNREACHABLE One of the default Maven repositories used to resolve build dependencies during analysis cannot be reached No action is needed where your organization mirrors these repositories internally, or where the machine is air-gapped. Act only where online builds actually fail to resolve their dependencies. Expected where you run the installer with --offline

Configuration

Unlike the other groups, this one reports a single line covering every parameter it validated. Where nothing is missing it reads:

All mandatory configuration parameters are set and all hostnames resolve.

A failure means either that a parameter required by the components you are installing carries no value, or that a hostname you have configured does not resolve. Set the missing value in your installer configuration, or correct the hostname and confirm that it resolves from this machine, then launch the installer again.

Which parameters are mandatory depends on the components selected and the deployment mode - see Configuration.

CAST package

Check Status Result detail Meaning What to do
configuration.conf present FAIL absent The main configuration file is missing from the installation package, or cannot be read Download and extract the installation package again - the copy on the machine is incomplete or corrupt
lib/ modules present FAIL absent The lib/ folder is missing from the installation package As above. The installer cannot start without it

Filesystem

Check Status Result detail Meaning What to do
INSTALL_DIR writable by user FAIL NOT writable (<dir>) The installing user cannot write to the nearest existing parent of INSTALL_DIR, /opt/cast by default, and non-interactive sudo -n is not available either Grant the installing user write permission on INSTALL_DIR or its parent, or make passwordless sudo available for that path
Installation folder empty FAIL NOT EMPTY (<folder>) The folder the selected components install into already holds content. This normally means CAST Imaging is installed on the machine already. Which folder is checked depends on the components being installed - see Installation folder Where CAST Imaging is already installed, run an update rather than an installation. Otherwise remove the existing content from the folder named in the message and launch the installer again

Where the check passes, the result detail is not present (<folder>) or empty (<folder>).

Shared storage

The shared, delivery and deploy folders are checked twice: once for readiness, and once for free space. The paths are read from your installer configuration for an all or imaging-services installation, and from the Control Panel configuration API for an analysis-node.

The folders are reported as Shared folder (common-data), Delivery folder and Deploy folder, each with a matching ... free space check.

Readiness means that the path resolves, that it is a directory where it already exists, and that the account running the check can perform every operation CAST Imaging needs there: browse, create, read, modify, rename and delete files, and create and remove directories.

For an all or imaging-services installation the folder does not have to exist yet, because the installation creates it. Where it does not, the check passes with ready (<source>: <location>) - not created yet, write access confirmed, which needs no action.

Status Result detail Meaning What to do
FAIL cannot determine location (<source>): <error> The path could not be resolved at all. On Microsoft Windows, SHARED_FOLDER, DELIVERY_FOLDER or DEPLOY_FOLDER is not set. On an analysis-node, the Control Panel configuration API did not return the property On Microsoft Windows, set the missing key in config-<component>.conf. On an analysis-node, check that the Control Panel is reachable and that application.paths.*-folder is set in its configuration
FAIL NOT a directory (<location>) The configured path exists, but it is a file rather than a folder Remove or rename the file, or point the configuration at a directory
FAIL NOT accessible (<location>) - does not exist; shared storage must already be set up by Imaging Services before installing an Analysis Node Reported on an analysis-node only: the folder does not exist yet Install imaging-services first, which creates the shared storage, then run the installer again on the node
FAIL NOT accessible (<location>) - drive letter not resolvable in this process On Microsoft Windows, a mapped drive letter such as Z: is not visible to the process running the check. A drive mapping exists only inside the session that created it, so Microsoft Windows services, differently elevated processes and installer custom actions cannot see it Use a UNC path such as \\server\share\imaging\deploy rather than a mapped drive letter
FAIL NOT accessible (<location>) - cannot create: <error> The folder does not exist and creating it failed, because of permissions or an over-long path for example Resolve the operating system error shown, or grant the installing account permission to create the folder tree
FAIL permission FAILED [<operations>] (<location>) One or more of the required operations failed for the account running the check. The operations that failed are listed in the message Grant that account full read, write, rename and delete permissions on the location. Every one of the required operations must succeed
WARN ready (<location>) - mapped network drive: invisible to Windows services, use a UNC path The path is reachable, but it is a mapped network drive that a Microsoft Windows service running under a different logon session cannot see Use a UNC path such as \\server\share\imaging\deploy before you go into production. Where you keep the mapped drive, the mapping must be made available to the service account - see Software requirements
WARN ready (<location>) - this location is on local disk, not shared storage The folder configured as shared storage is on local disk For a distributed deployment, point it at shared storage that every node can reach. Not reported for a single machine all installation, where the check does not apply
WARN ready (<location>) - not a mount point: ensure this is backed by real shared storage On Linux, the path is not itself a mount point, so the installer cannot confirm that shared storage is behind it Confirm the path is on a shared filesystem, an NFS mount for example, and not a local directory that happens to carry the same name

Shared storage free space

Status Result detail Meaning What to do
FAIL n/a - <error> The folder location could not be resolved, so its free space could not be measured Resolve the location first, using the readiness messages above
FAIL n/a (<dir>) Disk usage could not be read for the path Check that the filesystem or mount is reachable from this host
FAIL <N> GB (Below minimum) (<dir>) Free space is below the required minimum Free space, or point the folder at a volume with more capacity. See Disk space
WARN <N> GB (Minimum only) (<dir>) Free space is above the minimum but below the size CAST recommends Not blocking, but plan for more storage: deployment artifacts and working data grow with use

Free space at or above the recommended size passes and is reported as <N> GB (Recommended) (<dir>).

Resources

The CPU, memory and free disk space available to the components being installed, reported as RAM, CPU and Disk. Each result carries one of three states: Recommended passes, Minimum only warns, and Below minimum blocks for memory and disk. The report prints the minimum and the recommended value for each resource alongside the value it measured.

Status Result detail Meaning What to do
FAIL for memory and disk, WARN for CPU <N> GB (Below minimum) or <N> vCPU (Below minimum) The host does not meet the minimum for the components you selected Add memory or vCPU, or free disk space, to at least the stated minimum. See Hardware requirements and Disk space
WARN <N> GB (Minimum only) The host meets the minimum but not the size CAST recommends Not blocking. Consider sizing up for production use and for larger analyses, particularly disk
FAIL for memory and disk, WARN for CPU n/a or ? The value could not be measured, because /proc/meminfo could not be read for example This is an environment problem rather than a sizing one. Run the installer with --debug for more detail

Ports

Status Result detail Meaning What to do
FAIL IN USE (port <n>) The port a component needs on this host is already bound by another process. Where you have changed a port in your own configuration, your configured value is tested rather than the default Free the port by stopping the process holding it, or install the component on a different host. See TCP ports

Database

These checks run only where you use your own external PostgreSQL instance and a database host is resolved from your configuration.

Check Status Result detail Meaning What to do
Any database check WARN Database checks skipped Neither a psql client nor Docker or Podman is available on this host, so the database cannot be probed. The whole group is skipped and the installation continues Install a PostgreSQL client, or make Docker or Podman available so the installer can run psql from a temporary container, then run the installer again to have your instance validated
Any database check FAIL no psql, docker, or podman to probe the DB The same condition, reported against a single check As above
External DB reachable and authenticated FAIL no DB host (set DB_HOST or DB_MODE=external) No connection details were resolved from your configuration On Linux and Podman, set DB_MODE=external and DB_HOST in configuration.conf. On Microsoft Windows, configure CSS_INFOS
External DB reachable and authenticated FAIL connect/auth failed The host, port or credentials are wrong, or a firewall is blocking the connection Check the host, port, user, password and any SSL settings, and that the server accepts connections from this host
PostgreSQL >= 15 FAIL version unknown server_version_num could not be read Resolve the connection first, then run the installer again
PostgreSQL >= 15 FAIL server_version_num=<n> (< <required>) The instance is older than PostgreSQL 15 Upgrade the instance to a supported release. Checked on Linux only
Role can create user, database and schema FAIL role attributes unknown The attributes of the login role could not be read Resolve the connection first, then run the installer again
Role can create user, database and schema FAIL insufficient role (super=<0/1> createdb=<0/1> createrole=<0/1>) The configured login is not SUPERUSER and does not hold both CREATEDB and CREATEROLE. The installation creates a user, two databases and a schema Grant the role SUPERUSER, or grant it both CREATEDB and CREATEROLE
CREATE on pg_default tablespace WARN no CREATE on pg_default The role cannot create objects on the pg_default tablespace Grant CREATE on pg_default to the role, otherwise the installation fails when it creates the databases
Server encoding UTF8 WARN <encoding> (need UTF8) or unknown (need UTF8) The server encoding is not UTF-8, or it could not be read Recreate the target database, or the cluster, with UTF-8 encoding. A server that is not UTF-8 can corrupt analysis data, so resolve this warning before you install rather than after
No pre-existing control_panel or keycloak schema FAIL schema(s) already exist: <names> A control_panel or keycloak schema already exists in the target database. A second check reports quoted mixed-case variants such as "CONTROL_PANEL" or "Keycloak", which PostgreSQL does not fold to lower case Drop or rename the schemas listed, or point the installation at an empty database. The installation creates both schemas and cannot reuse existing ones
  • Installation prechecks - what each group validates and when it is run
  • Hardware - CPU, RAM, disk and TCP ports
  • Software - operating systems, Java, container engines and browsers
  • Database - PostgreSQL releases and configuration
  • Disk space - per-component disk usage and storage locations