Soviez logo

Troubleshooting

Troubleshooting

Symptom guide

Troubleshooting

For each issue: identify the symptom, run safe diagnostics, apply the recommended fix, then escalate to Soviez support if needed.

Never weaken security (open application ports, disable firewall, grant superuser) as the default fix.

Installation failed

Symptom: --init or --new stops with an error.

Check:

  • Ubuntu 22.04, 24.04, or 26.04 amd64
  • Root or sudo access
  • Sufficient disk space
  • Apt lock messages — wait for unattended-upgrades; do not killall apt

Fix: Read the error output, resolve the blocker, re-run the command. Use --doctor after --init to confirm host readiness.

Domain not resolving / TLS error

Symptom: Browser shows certificate or DNS errors for erp.example.com.

Check:

  • DNS A/AAAA record points to the server public IP
  • soviez.sh --ssl-status
  • Nginx configuration: sudo nginx -t

Fix: Correct DNS, then --ssl-try-again or --ssl-repair as indicated.

ERP inaccessible

Symptom: HTTPS timeout or 502/504 from Nginx.

Check:

  • Nginx listening on 443
  • Container health (via --doctor or operation logs)
  • Do not expose port 8069 publicly — ERP is served through Nginx on 443 only

Database connection errors

Symptom: ERP shows database errors in logs.

Check:

  • Docker network intact
  • PostgreSQL port 5432 is not published to the internet
  • Application uses the least-privilege role, not superuser

WebSocket / notifications broken

Symptom: Realtime updates or chat notifications do not appear.

Check: See WEBSOCKET_AND_LONGPOLLING.md. Verify /websocket proxy configuration. Do not publish port 8072 publicly.

PDF reports fail or timeout

Symptom: PDF generation returns 504 or blank output.

Check: See PDF_REPORTING.md. Confirm wkhtmltopdf is available in the ERP image and timeouts are adequate.

Update failed

Symptom: --update stops mid-operation.

Check:

soviez.sh --update-status <operation-id>
soviez.sh --security-update-check

Verify disk space, valid update entitlement, and exact --release ID. Use --update-recover or --update-rollback within the safety window if needed.

Operation waiting for you

Symptom: A long-running operation pauses and asks for confirmation, DNS, or review.

Check:

soviez.sh --operation-status <operation-id>
soviez.sh --operation-logs <operation-id>

Fix: Complete the required step (confirm flag, DNS record, security review). Reattach with --operation-reattach or the command-specific reattach flag. Do not start a duplicate operation.

Apt lock timeout

Symptom: Host package operations wait and eventually fail on apt lock.

Fix: Wait for unattended-upgrades or other apt jobs to finish. Schedule maintenance if needed. Never kill apt processes.

Backup or restore failed

Symptom: Backup verify fails or restore stops.

Check:

  • Passphrase configuration for encrypted backups
  • --backup-verify on the backup ID
  • Quarantine status for untrusted restores: --security-quarantine-status

Fix: Do not force promotion when scans report FAIL. Restore to Stage first if unsure.

Migration paused

Symptom: Migration transfer or cutover waiting.

Check:

soviez.sh --migration-status <operation-id>

Use transfer pause/resume, DNS try-again, or cutover rollback as documented. Never assume the source server was deleted.

Security scan REVIEW or FAIL

Symptom: --security-status or scan commands report REVIEW or FAIL.

Fix: Read --security-report, remediate findings, re-scan. Do not disable firewall or scanners to bypass findings.

Image download failed

Symptom: Install or update cannot download ERP images.

Check: See REGISTRY_TROUBLESHOOTING.md. Confirm entitlement, outbound HTTPS, and exact release ID.

SSH access lost after hardening

Symptom: Cannot SSH after security hardening.

Fix: Use your hosting provider console. Review SSH policy settings before re-running hardening.

Related

Source: canonical operator documentation · Permalink