Installation Troubleshooting — Common Errors During Installation

This page lists the symptoms most frequently encountered during or immediately after installation (Quick Install / Production Line / Air-Gapped Install), ordered from most to least frequent. For new installations on 2026.05+, container mode is the standard, and the tools/setup.sh-based Full H/W Setup is for legacy native maintenance only. For errors that occur during operation after installation, see the Container Mode Operations Guide or Diagnostics / Inspection.

Quick verification right after a 2026.05+ container mode install

sudo bash /opt/kopens/install/bin/status.sh   # 한 줄 상태
sudo bash /opt/kopens/install/bin/health.sh   # exit 0/1
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool   # image_tag / build_date / container_mode
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool   # components UP

If install.sh failed, check /var/log/kopens-install.log. If the container is unhealthy, run journalctl -u plantpulse-edge.service -n 100 or docker logs plantpulse-edge. Detailed scenarios: /opt/kopens/install/RUNBOOK.md inside the box (A–E matrix).

Preserve evidence before responding to a failure

On a box scheduled to go into production, capture doctor.sh and the acceptance log first, whenever possible, before reinstalling, cleaning, or restoring. Never share plaintext passwords.

sudo bash /opt/kopens/install/bin/doctor.sh || true
sudo journalctl -u plantpulse-edge.service -n 200 --no-pager \
  > /root/pp-edge-journal-$(date +%Y%m%d-%H%M%S).txt

1. Download / Installation Stage

1.1 `curl: (6) Could not resolve host: product.kopens.io`

Cause: DNS resolution failure.

Resolution:

nslookup product.kopens.io
# Server: ... (사내 DNS) — 응답이 없으면 DNS 가 안 풀림

# /etc/resolv.conf 확인
cat /etc/resolv.conf
# nameserver 8.8.8.8 또는 사내 DNS 가 있어야 함

# 임시로 공인 DNS 추가
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

If DNS is blocked on the corporate network, add the IP directly to /etc/hosts:

# product.kopens.io 의 실제 IP 를 운영팀에 문의 후 등록
echo "X.X.X.X product.kopens.io" | sudo tee -a /etc/hosts

At field sites where only product.kopens.io is open, check .com the same way.

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

Cause: The corporate firewall blocks outbound 443, or a proxy is required.

Resolution:

# 프록시 환경이면 export HTTP_PROXY / HTTPS_PROXY
export HTTPS_PROXY=http://proxy.company.local:8080
export HTTP_PROXY=http://proxy.company.local:8080

# 그 후 install.sh 다시 실행
bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)

If the proxy does not work either, transfer via USB using the Air-Gapped Install procedure.

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

Cause: The download was interrupted — insufficient disk space or a dropped link.

Resolution:

# 디스크 공간
df -h /opt /tmp

# 다시 다운로드 (`-C` 로 이어받기)
curl -O -C - https://product.kopens.io/plantpulse-edge/KOPENS_EDGE_V2026.tar.zstd

# 무결성 확인 (있으면 sha256)
sha256sum KOPENS_EDGE_V2026.tar.zstd

1.4 `bash: java: command not found`

Cause: Java is not installed. A 2026.05+ container installation normally has install.sh install the required packages, but if the package installation step fails due to corporate security policy or a blocked repo, a manual installation may be needed.

Resolution:

# Fedora / RHEL
sudo dnf install -y java-17-amazon-corretto-devel

# Ubuntu / Debian
sudo apt-get install -y temurin-17-jdk

# 확인
java -version
# openjdk version "17.x" ...

For a new container installation, resolve the cause of the package installation failure in install.sh first, rather than fixing Java by hand. Refer to (legacy) Full H/W Setup only for older native boxes.

1.5 `docker: command not found`

Cause: Docker is not installed, or the Docker installation step of install.sh failed.

Resolution:

# Fedora
sudo dnf -y install docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

# Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# 확인
docker --version

2. Boot / Startup Stage

2.0 Health returns 503 in container mode

Cause: One of the components is DOWN. Check the component name in the health JSON first.

Resolution:

curl -ks https://127.0.0.1/api/v1/system/health | python3 -m json.tool
sudo bash /opt/kopens/install/bin/status.sh
sudo bash /opt/kopens/install/bin/logs.sh tomcat | tail -100
sudo bash /opt/kopens/install/bin/logs.sh cassandra | tail -100
sudo bash /opt/kopens/install/bin/logs.sh mqtt | tail -100
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -100

Identify the cause in the per-component logs and act accordingly. If recovery is not achieved within 30 minutes, run backup.sh and doctor.sh per the escalation procedure in the Container Mode Operations Guide.

2.1 (legacy native) Stuck at the `[4] DB START` stage (60s+)

Cause: Cassandra is replaying the commitlog. This is normal on first boot or after an abnormal shutdown — it just needs more time.

Resolution:

# 별도 ssh 세션에서 실시간 로그
tail -f /opt/kopens/plantpulse-edge/db/logs/system.log

# `Listening for thrift clients` 또는 `Startup complete` 가 보이면 OK
# 그 후 메인 화면의 [4] 단계가 자동 진행됨

If there is still no message after 10 minutes — heap / disk / sstable corruption. Retry after bin/node-cleanup.sh.

2.2 (legacy native) Tomcat does not come up after `[7] SERVER START` — `Connection refused`

Cause A: Tomcat does not listen for 1–2 seconds right after boot — normal.

Cause B: Port 80 / 443 is held by another process.

Resolution:

# 포트 점유 확인
sudo ss -lntp | grep -E ':80 |:443 '

# 점유 중이면 그 프로세스 정리 (예: nginx)
sudo systemctl stop nginx

# tomcat 재시작
sudo /opt/kopens/plantpulse-edge/bin/restart.sh

Cause C: A startup error in catalina.out.

sudo tail -100 /opt/kopens/plantpulse-edge/server/logs/catalina.out | grep -E 'SEVERE|ERROR|Exception'

Act according to the message, e.g. Address already in use, Cannot find class, Failed to load app.properties.

2.3 Node-RED does not boot

Cause A: Port 1880 is occupied. Cause B: userDir (/opt/kopens/.../node/userDir) permissions. Cause C: flows.json is corrupted.

Resolution:

# 1880 포트 점유?
sudo ss -lntp | grep 1880

# userDir 권한
ls -la /opt/kopens/plantpulse-edge/node/userDir/

# Node-RED 로그 (container)
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -50

# Node-RED 로그 (legacy native)
tail -50 /opt/kopens/plantpulse-edge/node/log/node-red.log

# flows.json 손상 시 백업본으로 복원
cd /opt/kopens/plantpulse-edge/node/userDir
cp .flows.json.backup flows.json

# 재시작
/opt/kopens/plantpulse-edge/node/bin/stop.sh
/opt/kopens/plantpulse-edge/node/bin/start.sh

2.4 `INSTALL COMPLETED` is up but the web UI does not open (from outside)

Cause: The firewall blocks 80/443 (external access).

Resolution:

# 게이트웨이 자체에서는 되는지
curl -kI https://127.0.0.1/api/v1/system/health
# HTTP/1.1 200 이면 게이트웨이 정상, 외부 접근만 차단됨

# firewalld 확인
sudo firewall-cmd --list-all
# 80/tcp, 443/tcp 가 ports 에 없으면 추가

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

For iptables environments:

sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

3. Network / Time Synchronization

3.1 SSH drops after `set-1.sh` / `set-2.sh`

Cause: Wrong NIC IP / gateway / subnet entered.

Resolution (from the console — via KVM / IPMI / VM console):

# 현재 NIC 상태
nmcli dev show
ip a

# IP 수정 (예: enp1s0 의 IP 변경)
sudo nmcli con modify enp1s0 ipv4.address 192.168.0.50/24 ipv4.gateway 192.168.0.1
sudo nmcli con up enp1s0

# 재부팅 권장
sudo reboot

3.2 The clock reads 1970 / NTP does not synchronize

Cause: The chrony service is disabled or the NTP server is unreachable.

Resolution:

# chrony 상태
sudo systemctl status chronyd
# Active: inactive (dead) 면 시작
sudo systemctl enable --now chronyd

# 동기 강제
sudo chronyc makestep
sudo chronyc tracking
# Reference ID 가 채워지면 OK

# 사내 NTP 서버 사용 시 /etc/chrony.conf 의 server 라인 수정
# server <internal-ntp-ip> iburst

3.3 Internet traffic appears to leak onto the PLC network (NIC 2)

Cause: Both NICs have a default route.

Resolution:

# default route 확인
ip route | grep default

# 두 NIC 가 default 면 NIC 2 (PLC 망) 의 never-default 설정
sudo nmcli con modify enp2s0 ipv4.never-default yes
sudo nmcli con up enp2s0

4. Permissions / SELinux

4.1 `Permission denied` (binding port 80)

Cause: Running as a non-root user.

Resolution: Run all commands after sudo -i. If registered as a systemd service, it runs as root automatically.

4.2 `avc: denied` message (SELinux)

Cause: SELinux is in enforcing mode — some paths are denied.

Resolution:

# 임시로 SELinux 끄기 (테스트용)
sudo setenforce 0

# 영구 (운영 환경에서 비추천)
sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

# 정식: 거부된 path 에 컨텍스트 부여 (운영팀과 함께)
sudo semanage fcontext -a -t bin_t '/opt/kopens/.*\.sh'
sudo restorecon -Rv /opt/kopens

5. Disk

5.1 The `/data1` directory does not exist

Cause: The separate disk is not mounted.

Resolution:

# 현재 마운트
df -h

# /data1 이 없으면 디스크 인식 → mkfs → mount
lsblk
# /dev/sdb 같은 디스크 확인 후
sudo mkfs.xfs /dev/sdb
sudo mkdir -p /data1
sudo mount /dev/sdb /data1
echo '/dev/sdb  /data1  xfs  defaults,noatime  0 2' | sudo tee -a /etc/fstab

5.2 `/opt` disk full — extraction of artifacts fails

Resolution: Cleanup — clean.sh + node-cleanup.sh + delete old backups.

6. First Run — Data / Registration

6.1 Platform API Server card 🔴 Connection failed

Cause: server.host / port / username in app.properties is wrong, or the Platform is down, or the corporate firewall blocks outbound traffic.

Resolution:

# 외부에서 플랫폼 도달 가능?
curl -I https://<server.host>:<server.port>/

# 사내 방화벽 outbound 정책 — 운영팀에 문의 (HTTPS / 80 / 443)

# app.properties 수정 → 저장 → restart.sh

6.2 Edge ID is empty or not what you expected

Cause: edge.id in app.properties is not set.

Resolution: Environment Settings → edge.id=EDGE_<number> → Save → restart.sh.

6.3 Collection status stays at Unknown after registering a PLC

Cause A: Registered as auto_collect=false — a manual start is required. Cause B: The PLC network NIC is down, or the PLC IP is unreachable.

Resolution:

# PLC IP ping
ping -c 3 192.168.100.20

# PLC 포트 도달 (Modbus 502 예시)
nc -vz 192.168.100.20 502

# 도달 OK 면 화면에서 ▶ 시작 누르기

7. Other

7.1 The systemd `plantpulse-edge.service` service is not enabled

This is the standard service for container mode.

Resolution:

sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse-edge.service
sudo systemctl status plantpulse-edge.service --no-pager
sudo journalctl -u plantpulse-edge.service -n 100 --no-pager

If Unit not found, then /opt/kopens/install/install.sh failed before deploying the systemd unit. Check /var/log/kopens-install.log and then re-run bash /opt/kopens/install/install.sh.

7.2 (legacy native) The systemd `plantpulse.service` service is not enabled

Resolution:

# 서비스 파일 위치
ls -la /etc/systemd/system/plantpulse.service

# 없으면 등록
sudo cp /opt/kopens/tools/service/plantpulse.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse

# 상태
sudo systemctl status plantpulse
sudo journalctl -u plantpulse -n 100

7.3 Does not start automatically after reboot

sudo systemctl is-enabled plantpulse-edge.service
# enabled 가 아니면
sudo systemctl enable plantpulse-edge.service

For legacy native, apply the same procedure using plantpulse.service.

7.4 firefox / GUI tools will not install (server mode)

Cause: No GUI packages on a headless server.

Resolution: Safe to ignore; it does not affect gateway operation. Remove firefox from setup.sh, or exclude it from dnf install and continue.

8. Log Locations — Where to Look

Component	Log location
Tomcat (web / REST API)	`/opt/kopens/plantpulse-edge/server/logs/catalina.out`
Cassandra	`/opt/kopens/plantpulse-edge/db/logs/system.log`
HiveMQ (MQTT)	`/opt/kopens/plantpulse-edge/mqtt/log/hivemq.log`
Node-RED	`/opt/kopens/plantpulse-edge/node/log/node-red.log`
timeseries-engine	`/opt/kopens/plantpulse-edge/timeseries/engine/log/*.log`
systemd (container)	`journalctl -u plantpulse-edge.service -n 200`
systemd (legacy native)	`journalctl -u plantpulse -n 200`
Combined tail	`/opt/kopens/plantpulse-edge/bin/log-viewer.sh`

9. If It Still Does Not Work

In container mode, capture the output of status.sh, health.sh, and journalctl -u plantpulse-edge.service -n 200
In legacy native, monitor for 30 seconds with bin/log-viewer.sh → capture SEVERE / ERROR messages
Send the results of df -h, free -h, systemctl status ... along with the log excerpts above to the operations team
For a new box, re-run install.sh from Quick Install. Consider retrying tools/setup.sh from Full H/W Setup only for older native boxes.

10. Learn More

Standard procedure: Quick Install
legacy native: (legacy) Full H/W Setup
Air-gapped network: Offline / Air-Gapped Install
Post-installation checklist: Post-Install Checklist
Diagnostics during operation: Diagnostics / Inspection

1. Download / Installation Stage​

1.1 curl: (6) Could not resolve host: product.kopens.io​

1.2 curl: (7) Failed to connect to product.kopens.io port 443​

1.3 tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory​

1.4 bash: java: command not found​

1.5 docker: command not found​

2. Boot / Startup Stage​

2.0 Health returns 503 in container mode​

2.1 (legacy native) Stuck at the [4] DB START stage (60s+)​

2.2 (legacy native) Tomcat does not come up after [7] SERVER START — Connection refused​

2.3 Node-RED does not boot​

2.4 INSTALL COMPLETED is up but the web UI does not open (from outside)​

3. Network / Time Synchronization​

3.1 SSH drops after set-1.sh / set-2.sh​

3.2 The clock reads 1970 / NTP does not synchronize​

3.3 Internet traffic appears to leak onto the PLC network (NIC 2)​

4. Permissions / SELinux​

4.1 Permission denied (binding port 80)​

4.2 avc: denied message (SELinux)​

5. Disk​

5.1 The /data1 directory does not exist​

5.2 /opt disk full — extraction of artifacts fails​

6. First Run — Data / Registration​

6.1 Platform API Server card 🔴 Connection failed​

6.2 Edge ID is empty or not what you expected​

6.3 Collection status stays at Unknown after registering a PLC​

7. Other​

7.1 The systemd plantpulse-edge.service service is not enabled​

7.2 (legacy native) The systemd plantpulse.service service is not enabled​

7.3 Does not start automatically after reboot​

7.4 firefox / GUI tools will not install (server mode)​

8. Log Locations — Where to Look​

9. If It Still Does Not Work​

10. Learn More​

1. Download / Installation Stage

1.1 `curl: (6) Could not resolve host: product.kopens.io`

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

1.4 `bash: java: command not found`

1.5 `docker: command not found`

2. Boot / Startup Stage

2.0 Health returns 503 in container mode

2.1 (legacy native) Stuck at the `[4] DB START` stage (60s+)

2.2 (legacy native) Tomcat does not come up after `[7] SERVER START` — `Connection refused`

2.3 Node-RED does not boot

2.4 `INSTALL COMPLETED` is up but the web UI does not open (from outside)

3. Network / Time Synchronization

3.1 SSH drops after `set-1.sh` / `set-2.sh`

3.2 The clock reads 1970 / NTP does not synchronize

3.3 Internet traffic appears to leak onto the PLC network (NIC 2)

4. Permissions / SELinux

4.1 `Permission denied` (binding port 80)

4.2 `avc: denied` message (SELinux)

5. Disk

5.1 The `/data1` directory does not exist

5.2 `/opt` disk full — extraction of artifacts fails

6. First Run — Data / Registration

6.1 Platform API Server card 🔴 Connection failed

6.2 Edge ID is empty or not what you expected

6.3 Collection status stays at Unknown after registering a PLC

7. Other

7.1 The systemd `plantpulse-edge.service` service is not enabled

7.2 (legacy native) The systemd `plantpulse.service` service is not enabled

7.3 Does not start automatically after reboot

7.4 firefox / GUI tools will not install (server mode)

8. Log Locations — Where to Look

9. If It Still Does Not Work

10. Learn More