Troubleshooting

This section collects causes and actions for each symptom. Most issues can be narrowed down with the following three commands.

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                  # ① 컨테이너 상태 + 헬스 + 세션 수
curl -s localhost:5170/health       # ② 서버가 살아 있는가
docker logs --tail 100 plantpulse-studio-server   # ③ 무엇이 잘못됐는가

How to Read the Logs

Target	Command
Studio server (most important)	`docker logs -f --tail 200 plantpulse-studio-server`
Web (nginx)	`docker logs --tail 100 plantpulse-studio-web`
Builder sidecar	`docker logs --tail 100 plantpulse-studio-agent-server`
Follow with a script	`bash bin/logs.sh` (default server) · `bash bin/logs.sh studio-web`
Automatic backup	`tail -50 dist/backup.log`
App session container	Check the name with `docker ps --filter label=plantpulse-studio=1`, then `docker logs <name>`

Narrow down by time range

docker logs --since 30m plantpulse-studio-server
docker logs --since "2026-07-28T09:00:00" plantpulse-studio-server

Keys do not appear in logs

API keys and tokens are not recorded in logs (audit logs store only a fingerprint, not the value). When sending logs to support, just verify the site name and equipment name — that kind of field information.

One-Shot Check: "Can This Installation Do It?"

GET /api/v1/diagnostics     (관리자 전용)

This is where you start for inquiries like "The screen shows up, but the PDF doesn't come out" or "The app won't open."

{"ok": true,
 "os":        {"ok": true, "detail": "Debian GNU/Linux 13"},
 "chromium":  {"ok": true, "detail": "Chromium 153…"},
 "pdf":       {"ok": true, "detail": "26568 bytes"},
 "fontsCjk":  {"ok": true, "detail": "15 faces"},
 "docker":    {"ok": true, "detail": "server 29.8.1"}}

Each item is {ok, detail}, and the top-level ok is true only if all are true. pdf is the result of actually baking a Korean PDF, not just an explanation, and docker checks whether a session container can be launched.

This is a different question from /health — do not poll from the screen

/health asks "is it alive" cheaply and frequently, whereas diagnostics ask "can it do the work" expensively and occasionally (it actually bakes a PDF). Calling it periodically from a dashboard would itself become a load.

Symptom → Cause Quick Lookup

Symptom	Common Cause	Check	Action
Web screen doesn't open at all	Stack is down, or port 80 is occupied	`bash bin/status.sh` `docker logs plantpulse-studio-web`	`bash bin/up.sh` · Stop other services using port 80
Screen shows, but login fails	Bootstrap account not set, or platform unreachable	`grep STUDIO_LOCAL_USERS .env` `curl -s localhost:5170/health`	Specify an account in `.env`, then `bash bin/restart.sh`
Login suddenly blocked (retry after a while)	Login rate limit (10 attempts/min per IP)	`docker logs --tail 50 plantpulse-studio-server`	Wait 1 minute and retry
Health stays DOWN, DB auth error in logs	Only the password in `DATABASE_URL` was changed, not the role inside the DB	`docker logs plantpulse-studio-server` Connect directly from an external PG using `psql`	Revert to the original password, or first change the account password inside PostgreSQL
Opening a project fails (500)	Session runtime image missing	`docker image inspect plantpulse-studio-runtime:latest`	Re-run `bash bin/up.sh` (for air-gapped, import with `bin/load.sh`)
Preview or deployed app shows blank screen (IP access)	Firewall blocks 5171	`curl -I http://<server-ip>:5171/`	Open port 5171 in the firewall
Preview blank + console `Mixed Content`	Studio is HTTPS, but app assets are requested over HTTP	Browser dev tools console	Add `X-Forwarded-Proto $scheme` to the proxy → Domain
Preview doesn't update even after code changes	Proxy doesn't upgrade the HMR WebSocket	Dev tools → Network → check whether WS requests are 101	Add `Upgrade`/`Connection` headers to both vhosts
Build chat times out with "network error"	Proxy send timeout (default 60s)	Check proxy vhost settings	Add `proxy_read_timeout 3600s` to both vhosts
Replies arrive in chunks, not real-time	`proxy_buffering` enabled (default)	same	`proxy_buffering off`
Any domain goes to the wrong place	web nginx config load order (first `server` is the default server)	`docker exec plantpulse-studio-web ls /etc/nginx/conf.d`	Rename the vhost file to start with `zz-`
Deployed app gets 401 for real data	① Session logged in before domain separation ② Platform key not set	Log out and log in again Environment settings → Platform tab	① Log in again once ② Set `PLATFORM_API_KEY`, then `bin/restart.sh`
Key change not reflected	Only `.env` was changed, but `docker restart` doesn't re-read `.env`	Check whether the badge on the Environment settings screen is `환경변수 기본값`	Fast path — enter the new key in the Environment settings screen (applies immediately without restart). If you must change the environment variable, use `bash bin/restart.sh` (or `docker compose up -d --force-recreate`)
App build fails with a "sidecar" error	Builder sidecar not running	`docker ps --filter name=plantpulse-studio-agent-server` `curl -s localhost:8000/health`	`bash bin/restart.sh` · In a hurry, switch the builder engine to built-in via Environment settings → Agent
Chat shows "Cannot connect to AI provider `<address>`. Check the address and key in Environment settings → AI tab."	AI address/key error, gateway down	Environment settings → AI tab → Connection Test `docker logs --tail 50 plantpulse-studio-server`	Correct the address/key on the screen — applies immediately (no restart needed)
Chat shows "AI provider is not configured (Environment settings)."	AI provider completely empty	Environment settings → AI tab	Enter the address/key and click [Connection Test]
3D or large app build dies midway	Out of memory (session container limit 2 GB, host capacity)	`docker stats` · `free -h`	Reduce simultaneously open projects · Increase host memory
Automatic backup doesn't run	cron not installed, or DB unreachable	`cat /etc/cron.d/pp-studio-backup` `tail -50 dist/backup.log`	Reinstall `sudo bash bin/install-backup-cron.sh` · Verify DB reachability with `DRYRUN=1 bash bin/restore.sh`
Disk full	Backup and build artifacts accumulate	`df -h` `du -sh dist /var/lib/pp-studio/*`	Reduce retention count (`BACKUP_KEEP`) · Clean up old backups
Updated, but old screen still shows	Browser cache, or image pull failed	Hard refresh in browser (Ctrl+Shift+R) Pull result in `bash bin/update.sh` output	Verify registry login, then re-run `bash bin/update.sh`

Detailed Diagnostics

When the Stack Won't Start

cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh
docker ps -a --filter name=pp-studio          # Exited 인 컨테이너 찾기
docker logs --tail 200 plantpulse-studio-server

If a container keeps restarting (Restarting), the last line of its log holds the cause. The most common ones are a database connection failure and an incorrect .env value.

grep -E '^(DATABASE_URL|COMPOSE_PROFILES|PG_|DATA_ROOT|PLATFORM_API_TARGET)' .env

One-Shot Verdict: Is the Installation "Healthy"?

bash bin/smoke-install.sh

It checks health, unauthenticated setup API, web response, actual login, session runtime image, and container state in order, and tells you the first failing item.

App Session (Project Open) Issues

docker ps --filter label=plantpulse-studio=1     # 지금 떠 있는 세션 컨테이너
docker image inspect plantpulse-studio-runtime:latest >/dev/null && echo "런타임 이미지 OK"

Session containers are automatically reaped after 30 minutes idle — absence from the list is not an error.
Restarting the server automatically cleans up any remaining session containers.
Multiple users opening projects simultaneously consume memory accordingly (check with docker stats).

Platform (Real Data) Connection Issues

Symptoms are usually "chat queries work, but no values come back" or "the equipment list is empty."

In Environment settings → Platform tab, check the connection status.
Verify the PLATFORM_API_TARGET address in .env.
Check that PLATFORM_API_KEY is configured → Secret Management
Check the server logs for platform call errors.

docker logs --tail 200 plantpulse-studio-server | grep -i platform

If the platform is temporarily down, watcher runs are automatically skipped (and resume automatically after restart).

Domain and Proxy Issues

Symptoms vary, but the cause is usually one of four settings missing. Compare against the checklist in Domain and Reverse Proxy.

Recovery Options

Situation	Action
Misconfigured settings causing stack issues	Revert with `.env`, then `bash bin/restart.sh`
Data corrupted	Backup and Restore — `bash bin/restore.sh`
Issues after an update	Pin `PP_IMAGE_TAG` in `.env` to the previous version, then `bash bin/update.sh`
Issues with a deployed app	Roll back to a previous version from the deployment history in the Studio screen

Useful to Include When Requesting Support

cd /opt/kopens/plantpulse-studio-docker

bash bin/status.sh                    > /tmp/pp-status.txt
docker logs --tail 500 plantpulse-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env    > /tmp/pp-env-safe.txt   # 비밀 제외본

When it started, and what operation triggered it
Screen capture (even better if it includes the browser dev tools console)
Installation version (PP_IMAGE_TAG in .env, or the CalVer in VERSION if empty) and access method (IP / domain / whether a proxy is used)

Before sending logs or configuration

The .env original contains API keys. Make a copy with secrets removed, as described above, before sending.

How to Read the Logs​

One-Shot Check: "Can This Installation Do It?"​

Symptom → Cause Quick Lookup​

Detailed Diagnostics​

When the Stack Won't Start​

One-Shot Verdict: Is the Installation "Healthy"?​

App Session (Project Open) Issues​

Platform (Real Data) Connection Issues​

Domain and Proxy Issues​

Recovery Options​

Useful to Include When Requesting Support​

Related Documents​