Troubleshooting
This section collects symptoms, causes, and remedies. Most issues can be narrowed down with these 3 commands:
cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh # ① 컨테이너 상태 + 헬스 + 세션 수
curl -s localhost:5170/health # ② 서버가 살아 있는가
docker logs --tail 100 pp-studio-server # ③ 무엇이 잘못됐는가
How to view logs
| Target | Command |
|---|---|
| Studio server (most important) | docker logs -f --tail 200 pp-studio-server |
| Web (nginx) | docker logs --tail 100 pp-studio-web |
| Database (bundled mode) | docker logs --tail 100 pp-studio-postgres |
| Builder sidecar | docker logs --tail 100 pp-studio-agent-server |
| Follow via script | bash bin/logs.sh (default server) · bash bin/logs.sh studio-web |
| Automatic backup | tail -50 dist/backup.log |
| App session container | docker ps --filter label=plantpulse-studio=1 to confirm name, then docker logs <name> |
Narrow down by timestamp
docker logs --since 30m pp-studio-server
docker logs --since "2026-07-28T09:00:00" pp-studio-server
API keys are not logged
API keys and tokens are never recorded in logs (audit logs show only fingerprints, not values). When sharing logs with support, you only need to confirm field information such as site name and equipment name.
Symptom → cause quick reference
| Symptom | Common cause | Check | Remedy |
|---|---|---|---|
| Web page will not open at all | Stack is down or port 80 is in use | bash bin/status.shdocker logs pp-studio-web | bash bin/start.sh · Stop other services using port 80 |
| Page loads but login fails | Bootstrap account not set, or Platform unreachable | grep STUDIO_LOCAL_USERS .envcurl -s localhost:5170/health | Set account in .env then bash bin/restart.sh |
| Login suddenly blocks (retry after a moment) | Login rate limit (10 attempts/min per IP) | docker logs --tail 50 pp-studio-server | Wait 1 minute and retry |
| Health stays DOWN, DB auth error in logs | Changed PG_PASSWORD when old data exists | docker logs pp-studio-postgresdocker logs pp-studio-server | Revert to original password, or change account password first inside PostgreSQL |
| Project open fails (500) | Session runtime image missing | docker image inspect plantpulse-studio-runtime:latest | Re-run bash bin/start.sh (air-gapped: import via bin/load.sh) |
| Preview or deployed app shows blank screen (IP access) | Firewall blocks port 5171 | curl -I http://<server-ip>:5171/ | Open port 5171 in firewall |
Preview blank + console Mixed Content | Studio is HTTPS but app assets request HTTP | Browser DevTools console | Add to proxy: X-Forwarded-Proto $scheme → domain |
| Preview unchanged after code fix | Proxy does not upgrade HMR WebSocket | DevTools → Network → WS request returns 101 | Add Upgrade/Connection headers to both vhosts |
| Build chat takes long, then "Connection error: network error" | Proxy send timeout (default 60s) | Check proxy vhost config | Add proxy_read_timeout 3600s to both vhosts |
| Responses appear in chunks, not streamed | proxy_buffering is on (default) | 〃 | proxy_buffering off |
| Any domain redirects to wrong place | Web nginx config load order (first server is default server) | docker exec pp-studio-web ls /etc/nginx/conf.d | Rename vhost filename to start with zz- |
| Deployed app returns 401 for real data | ① Session logged in before domain split ② Platform key not set | Try logout → re-login Settings → Platform tab | ① Re-login once ② Set PLATFORM_API_KEY then bin/restart.sh |
| Key changed but not applied | docker restart does not re-read .env | Settings shows "Managed by environment variable" | bash bin/restart.sh (or docker compose up -d --force-recreate) |
| App build fails with "sidecar" error | Builder sidecar not running | docker ps --filter name=pp-studio-agent-servercurl -s localhost:8000/health | bash bin/restart.sh · If urgent, switch builder engine to embedded in Settings → Agent |
| Chat returns "AI provider unreachable" | AI address or key wrong, or gateway down | Settings → AI tab Connection testdocker logs --tail 50 pp-studio-server | Fix address/key → bin/restart.sh |
| 3D or large app build dies mid-build | Out of memory (session container limit 2 GB, host available) | docker stats · free -h | Reduce open projects · Increase host memory |
| Automatic backup does not run | cron not installed or DB unreachable | cat /etc/cron.d/pp-studio-backuptail -50 dist/backup.log | Reinstall sudo bash bin/install-backup-cron.sh · Verify DB reachable with DRYRUN=1 bash bin/restore.sh |
| Disk full | Backup and build artifact accumulation | df -hdu -sh dist /var/lib/pp-studio/* | Reduce retention count (BACKUP_KEEP) · Clean old backups |
| After update, old screen persists | Browser cache or image pull failed | Hard refresh browser (Ctrl+Shift+R) Check pull result in bash bin/start.sh output | Verify registry login then re-run bash bin/start.sh |
Detailed diagnosis
When the stack does not start
cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh
docker ps -a --filter name=pp-studio # Exited 인 컨테이너 찾기
docker logs --tail 200 pp-studio-server
If a container keeps restarting (Restarting), the cause is on the last line of its logs. Most common are database connection failure and .env value error.
grep -E '^(DATABASE_URL|COMPOSE_PROFILES|PG_|DATA_ROOT|PLATFORM_API_TARGET)' .env
Determine if installation is "in good state" with one check
bash bin/smoke-install.sh
Inspects health · unauthenticated settings API · web response · actual login · session runtime image · container status in order, and reports the first failed 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 auto-reclaimed after 30 minutes idle — absence from the list is not an error.
- Restarting the server auto-cleans leftover session containers.
- Multiple concurrent users consume memory accordingly (check with
docker stats).
Platform (real data) connection issues
Symptoms are usually "chat queries work but no values return" or "equipment list is empty."
- Go to Settings → Platform tab and check connection status.
- Verify the
PLATFORM_API_TARGETaddress in.envis correct. - Check that
PLATFORM_API_KEYis set → Secret management - Check server logs for Platform call errors.
docker logs --tail 200 pp-studio-server | grep -i platform
If Platform briefly goes down, watcher runs are automatically skipped (resume auto-restart).
Domain and proxy issues
Symptoms vary, but the cause is usually one of 4 missing settings. Match against the checklist in Domain and reverse proxy.
Recovery options
| Situation | Remedy |
|---|---|
| Config was mishandled, stack has issues | Restore .env then bash bin/restart.sh |
| Data is corrupted | Backup and recovery — bash bin/restore.sh |
| Problem after update | Pin TAG in .env to previous version then bash bin/start.sh |
| Deployed app has issues | Rollback to previous version in deployment history on Studio screen |
Good to send with support requests
cd /opt/kopens/plantpulse-studio-docker
bash bin/status.sh > /tmp/pp-status.txt
docker logs --tail 500 pp-studio-server &> /tmp/pp-server.log
grep -vE 'KEY|TOKEN|PASSWORD' .env > /tmp/pp-env-safe.txt # 비밀 제외본
- When it started and what action triggered it
- Screenshot (include browser DevTools console if possible)
- Installation version (
TAGin.env) and access method (IP / domain / proxy or none)
Before sharing logs or config
.env original contains API keys. Make a copy excluding secrets as shown and send that.