Troubleshooting

This guide covers common issues during install, startup, access, USIP, import/export, and upgrades.

Scope

Docker Compose or K8s deployments
USIP and Event Sync integrations
Import/export issues

Quick Triage

Symptom	Immediate Action	Next Step
One-click script stuck	`curl -I https://get.univer.ai`	Use offline package
Demo UI not accessible	`cd univer-server && bash run.sh start`	`docker compose ps`
USIP demo 8080 returns 404	Check `USIP_ENABLED=true` in `.env.custom`	`bash run.sh restart`
Helm pods Pending	`kubectl describe pod`	Check image/resources/PVC
Import/export Pending	Check temporal/exchange/universer logs	See Import/Export section

Docker Compose Issues

Install Failed

Check network:

curl -I https://get.univer.ai
dig get.univer.ai

Docker installation conflicts:

systemctl status docker
ps -ef | grep dockerd

Services Not Running / Restarting

cd univer-server
bash run.sh start
docker compose ps
docker compose logs --tail=200 <service>

Common causes: port conflicts, .env.custom not loaded, insufficient resources.

Demo UI Issues

Port conflict: lsof -i :3010
WebSocket disconnect: check reverse proxy/CORS
Auto-create doc failure: check universer logs

K8s Issues

Pod Pending

kubectl describe pod <pod> -n univer

Check: image pull, PVC, node resources.

CrashLoopBackOff

kubectl logs <pod> -n univer --previous

Ingress / Domain Access Failure

dig univer.example.com
kubectl get ingress -n univer
kubectl get endpoints -n univer

USIP Issues

Symptom	Cause
8080 not responding	Ensure `bash run.sh start-demo-usip` is executed
401/403 after enabling USIP	Check token pass-through and user response
Config not applied	Restart after editing `.env.custom`

Import/Export Pending

Investigation Path

Disable VPN/proxy → bash run.sh restart
Service status → docker compose ps
Temporal logs → docker compose logs -f temporal
Exchange logs → docker compose logs -f univer-worker-exchange
Universer logs → docker compose logs -f universer

Common Errors

Temporal startup failure: port conflict or database issues
Exchange timeout: check Temporal address

Example: update exchange/config.yaml.template and restart:

addr: no-txt:///${TEMPORAL_HOST}:${TEMPORAL_PORT}

Upgrade & Uninstall

Docker Compose upgrade: rerun installer in parent directory
K8s upgrade: helm upgrade --install ... -n univer
Data still exists after uninstall: check PVC reclaim policy or volumes

Logs & Collection

Service	Command
temporal	`docker compose logs -f temporal`
exchange	`docker compose logs -f univer-worker-exchange`
universer	`docker compose logs -f universer`

Package logs:

mkdir -p logs_collect && \
docker compose logs temporal > logs_collect/temporal.log 2>&1 && \
docker compose logs universer > logs_collect/universer.log 2>&1 && \
tar czf univer-troubleshoot-logs.tar.gz logs_collect

Checklist

Services are Up / Pods Ready
No errors in temporal/exchange
Ports and domains are accessible
Config changes applied after restart
Import/export tasks can complete

Table of Contents