Self-Host Troubleshooting

Use this page for common high-probability failures.

Deploy fails with port already allocated

Likely cause:

• stale compose project still publishing required port

Fix:

• stop/remove old stack and rerun deploy

SynckHub cannot sync with Common

Likely cause:

• invalid or stale infra token

Fix:

• re-mint infra token through reconcile workflow
• redeploy SynckHub host with updated Vault secret

Browser auth/session behaves inconsistently

Likely cause:

• origin/cookie mismatch across UI and Common

Fix:

• validate Common public base URL and allowed origins
• keep UI/Common in compatible same-site cookie topology

WOPI actions return service unavailable

Likely cause:

• discovery fetch unavailable or misconfigured public WOPI base URL

Fix:

• verify discovery URL reachability and WOPI public host routing

Coauthoring fails after partial config

Likely cause:

• required integration secrets/pins are missing

Fix:

• enforce complete integration configuration before enabling feature paths