Installation & Setup Issues

Problems that show up while installing OpsIQ or getting it running for the first time. For errors you see while using OpsIQ, see Runtime Issues.

The installer checks the target before it changes anything, so most problems are caught up front with a clear message. The common ones, and how to resolve them, follow below. If you need to contact Fresche support, see The installer's transcript log at the end of this page.

The installer command is "not found"

Symptom

Your terminal rejects the command before the installer runs at all — opsiq-install: command not found (macOS, Linux, Git Bash), The term 'opsiq-install.exe' is not recognized as a name of a cmdlet, function, script file, or executable program (PowerShell), or 'opsiq-install.exe' is not recognized as an internal or external command (Command Prompt).

Cause

In PowerShell and in any Unix-style shell, the current folder is not searched for programs, so the bare name is not found even when the file is sitting right there — you left off the ./ or .\ prefix. Command Prompt does search the current folder, so there the same message means something different: you are not in the folder you unzipped into.

Fix

Change into the folder you unzipped the installer into, then check it runs with the prefix for your terminal:

macOS / Linux

./opsiq-install --help

Windows (PowerShell or Command Prompt)

.\opsiq-install.exe --help

Windows (Git Bash)

./opsiq-install.exe --help

If that prints the usage text, the prefix is right and you can re-run your real install command. The prefix depends on your terminal, not just your OS: .\opsiq-install.exe is right for PowerShell and Command Prompt, but Git Bash needs ./opsiq-install.exe — it treats \ as an escape character and reports the confusing .opsiq-install.exe: command not found. Command Prompt is the reverse, rejecting ./ with '.' is not recognized. In WSL, use the Linux download and ./opsiq-install. The full list is under Get the installer.

A required program is missing

Symptom

The installer stops early naming a missing prerequisite — for example Node <version> is too old, PM2 not found on the target, or openssl not found.

Cause

The IBM i is missing one of OpsIQ's prerequisites, or has a version that is too old.

Fix

Install the missing components on the IBM i (in a PASE shell) and re-run the installer. OpsIQ requires Node.js 22 (the nodejs22 package, version 22.15 or later), PM2, and openssl. The first line puts /QOpenSys/pkgs on PATH — without it yum itself reports not found.

PATH=/QOpenSys/pkgs/lib/nodejs22/bin:/QOpenSys/pkgs/bin:$PATH; export PATH
yum install nodejs22 openssl && npm i -g pm2

Another prerequisite check failed

Symptom

The installer stops at Checking prerequisites with one of these messages:

• the qsh `db2` utility is not available on the target
• <your user> lacks *ADD and *OBJMGT on license library <library>
• cannot write the install root <path> as <your user>

Cause

Beyond Node.js, PM2 and openssl, the installer checks a few more things before it changes anything. It records each instance in a registry kept in the license library, and writes that entry with the QShell db2 utility, so it needs that utility and *ADD and *OBJMGT authority to the library. It also needs to be able to create and write the install directory.

Fix

For db2, install QShell and the Db2 query tools on the IBM i. For the library, grant your SSH user the authority the message names (it prints the GRTOBJAUT command), or point --license-library at a library that user can write. For the install directory, choose a path your SSH user can write with --install-root, or sign in with a profile that has authority over it. Then re-run the installer.

On an upgrade you may also see a low disk space warning, when the disk looks too small to hold the pre-upgrade snapshot. It is a warning only — the upgrade continues. Free some space, or lower --keep-backups, if the snapshot then fails.

A warning about Node.js or PM2 security fixes

Symptom

During Checking Node and PM2 for security fixes, the installer warns that the IBM i's Node.js or PM2 is missing security fixes, or that it could not complete the check.

Cause

The installer compares the Node.js and PM2 versions on the IBM i against published security releases and advisories. To do so it contacts nodejs.org, raw.githubusercontent.com and api.osv.dev from your workstation. If your workstation cannot reach them — for example, behind a firewall — the check cannot run.

Fix

This check never stops the install; it only warns. Update Node.js or PM2 on the IBM i when you can. If the check could not run, allow your workstation to reach those sites, or carry on without it.

Ports already in use

Symptom

A message that one or more ports are already in use, naming the port flags.

Cause

Another program on the IBM i is already listening on OpsIQ's default ports (3000, 3939, 8445).

Fix

On a fresh install the installer normally moves a busy port to the next free one automatically. If it cannot find one, it stops with no free port for the <component> component near <port>. Choose your own with --server-port, --tools-port, and --web-port — see Installation Options. An upgrade keeps the instance's existing ports rather than moving them.

The install user is not authorized

Symptom

The installer stops during its prerequisite check with one of these messages:

• service profile OPSIQ / JOBD QGPL/OPSIQJOBD not found
• <your user> cannot chown to OPSIQ (needs *ALLOBJ)
• <your user> cannot SBMJOB as OPSIQ (needs *USE to the profile + *JOBCTL)

Cause

The default (managed) install hands the services off to a dedicated OPSIQ profile. That requires the profile and its job description to exist, and the SSH login you install with to hold *ALLOBJ (to hand the install directory to the profile), *USE authority to the profile, and *JOBCTL (to submit the services as it).

Fix

If the profile does not exist, re-run with --provision-profile to have the installer create it (this needs an SSH user with *SECADM). If an authority is missing, sign in with a profile that has it. Either way, you can instead perform a direct install, where the services run under your own profile and none of these authorities is needed — add --service-user set to your SSH user; see managed vs. direct in Configuration.

The "not found" message also prints a one-time provision-profile.sh command; use --provision-profile or a direct install instead.

The Terms & AI Disclaimer were not accepted

Symptom

The installer prints the Terms & AI Disclaimer notice and stops without installing anything, showing Terms & Conditions and AI Disclaimer not accepted — installation aborted.

Cause

OpsIQ will not install until you accept the Terms & Conditions and acknowledge the AI Disclaimer. Either you answered something other than yes, or the run was non-interactive and the acceptance flag was not provided.

Fix

Review both documents — Terms & Conditions (English, French) and the AI Disclaimer (English, French) — then re-run and answer yes at the prompt, or pass --accept-license yes for a non-interactive run. The prompt accepts only the full word yes; y does not work.

The license key was rejected

Symptom

The installer reports invalid OpsIQ license key — expected a 43-character base64 license key. (at the interactive prompt it asks for the key again), or reports that every one of the <n> slots in <library>/PW_407 is occupied, or the final health check fails on the tools server with a 503.

Cause

The key is mistyped, expired, or not an OpsIQ key. Keys are exactly 43 characters of base64 (letters, digits, + and /). The "slots occupied" message means the license data area in that library already holds as many keys as it can, so the new key cannot be added without overwriting one. A 503 from the tools server with a key you know is valid can also mean the profile the services run under cannot read the PW_407 data area.

Fix

Check the key against what your Fresche contact provided. If it is correct but still rejected, it may be expired — see Licensing. If the box already has a valid key and you are reinstalling, use --skip-license. If every slot is occupied, install this instance with its own --license-library rather than a shared one. For a 503, read the installer's health-check failure message. The tools server itself only reports that the licence data area could not be read, but the installer's message names the library and the service profile, and includes the command to grant read access, in this form (run it on an IBM i command line):

GRTOBJAUT OBJ(<library>/PW_407) OBJTYPE(*DTAARA) USER(<profile>) AUT(*USE)

Checking the data area while signed in as your own SSH user does not test this, because the services read it as their own profile.

The install failed at a health check

Symptom

✗ Install failed at: <step>, followed by the last lines of a service's log.

Cause

The services were installed but one did not come up cleanly. The step name tells you which service — tools, server, or web.

Fix

Read the log lines the installer printed; they usually name the cause. A 503 from the tools server points to a license problem — see The license key was rejected. If this was an upgrade, the installer has already rolled back to the previous version (unless you passed --rollback=false or --backup=false). You can also view the log on the IBM i directly, in a PASE shell (replace the service name with the one named in the failure). The two setup lines are required — see PASE shell setup:

PATH=/QOpenSys/pkgs/lib/nodejs22/bin:/QOpenSys/pkgs/bin:$PATH; export PATH
PM2_HOME=/QOpenSys/opsiq/opsiq/.pm2; export PM2_HOME
pm2 logs opsiq-server-opsiq --err

Sign-in fails with a 503 after install

Symptom

The web UI shows Authentication service temporarily unavailable for every user, or the installer's health check fails on server→tools login round-trip with a 503 and adds a note that the AI server's TOOLS_API_KEY may not match the tools server's key file.

Cause

The AI server's copy of the tools server's caller key does not match the key file on the IBM i, so the tools server turns the AI server away. The AI server's error log says rejected this server's caller key (HTTP 401) and TOOLS_API_KEY does not match tools-api.key. On a split install this happens when the --role app run has not yet followed the --role tools run, or used a key from an older install.

Fix

Re-run the installer. For a split install, run --role tools and then --role app, back to back, from the same workstation, and pass the tools server's key to the --role app run with --tools-api-key-file: the copy the --role tools run saved at ~/.opsiq/secrets/<instance>@<tools-host>.tools-api.key, or a copy of the key file from the IBM i. Without the flag, an upgrade keeps the key the AI server already holds. See What to install (roles). If sign-in still fails with a 503 after that, the cause is elsewhere, such as the AI server not trusting the tools server's certificate; its error log names it.

The tools server does not start

Symptom

opsiq-tools-<instance> keeps restarting or shows errored in pm2 list, and the installer's health check fails on the tools server.

Cause

The tools server refuses to start without a valid key file, <install-root>/apps/ibm-opsiq-tools/tools-api.key. Its error log has a line containing server.api key unusable; refusing to start, with the file's path and the reason — for example, that the file is missing, or holds characters it does not accept.

Fix

Re-run the installer against the IBM i (with the same --role and --instance you installed with). It keeps a valid key and creates a new one when the file is missing or unusable. Do not create or edit the file by hand. On a split install, follow with the --role app run so the AI server receives the new key — see Sign-in fails with a 503 after install. How to read the log is under Viewing the logs.

A split install stops at preflight: no tools API key

Symptom

A --role app run stops before changing anything with split install: no tools API key for instance <name> on <tools-host>, or reports that the --tools-api-key-file it was given is missing or does not hold a valid tools API key.

Cause

The AI server needs the tools server's caller key. The installer takes it, in order, from the file you pass with --tools-api-key-file, then (on an upgrade) the key the AI server already holds, then the copy a --role tools run on this workstation saved for that host. That copy is found only when the --role tools run's --host is the name this run gives as --tools-host. None of them has a key, or the file you passed is not a copy of the key. A file you pass is never skipped over: when it is wrong, the run stops.

Fix

Run --role tools for the same instance from this workstation first, then the --role app run again. If the tools install was run from another workstation, copy <install-root>/apps/ibm-opsiq-tools/tools-api.key from the IBM i to this one over a secure channel and pass it with --tools-api-key-file. See What to install (roles).

Connection to the IBM i drops

Symptom

The installer cannot connect, times out, or the SSH session drops partway through.

Cause

A network path or firewall problem, SSH not running on the IBM i, or an unrecognized host key on first connect.

Fix

Confirm you can ssh to the box by hand with the same user. If it is the first time connecting and the installer stops on an unknown host key, you can confirm the key's fingerprint and allow it — see the host-key options in Installation Options.

The installer's transcript log

Every run writes a transcript — a log of what it ran and what came back. The last thing the installer prints is its location, as Transcript: <path>, followed by the reminder Fresche support only — read it before sending; redaction is best-effort.

By default the file goes in an opsiq-logs folder beside the installer program, or in opsiq-logs in your home directory if the installer cannot write beside itself. Each file is named after the time of the run and its process number. To choose the folder, set OPSIQ_LOG_DIR in your workstation shell before running the installer; to turn the transcript off, set OPSIQ_LOG=off.

The installer removes the secrets it knows about (keys and passwords) from the transcript, but that removal is best-effort. Read the file before you send it to Fresche support, and send it only to them.