Skip to content

Troubleshooting

When something goes wrong with a subscription, start here. Most issues fall into one of six categories — DNS, Nginx, instance provisioning, SSH, backups, or notifications. Use the symptom table below to find the right page, and always run Diagnosis & Fix before digging in manually.

Common Symptoms

Symptom Go to
Subscription stuck in Build Failed Build Failed
Customer can't reach the URL (502, timeout) Build Failed → Nginx step
DNS resolves but site returns SSL error DNS Not Resolving
DNS not resolving at all DNS Not Resolving
SSH actions fail (Git, VS Code, SSH Console) SSH Connection Issues
Backups not running or backup state shows Danger Backup Failures
Customer not receiving push notifications Notification Issues
Diagnosis & Fix button not available Concepts: SaaS Slave

Pre-Diagnostic Checklist

Run these five steps before opening a specific troubleshooting page. They cover the most common root causes and save time.

  1. Check the Build Fail Message — open the subscription form and look for the red banner near the top of the page. The same message is also in the Build Steps section. It usually identifies the exact step and error.

  2. Run Diagnosis & Fix — click Action → Diagnosis & Fix on the subscription form (requires SaaS Slave — a feature that gives the customer instance self-service control over module installation and management). A "started in background" message appears in the chatter immediately. Wait 10–60 seconds for the full HTML report to appear. Each component is marked ✅, ⚠️, or ❌.

  3. Test each infrastructure connector — on the form for each external service (NPM server, Portainer environment, Cloudflare account, Backup server), click Test Connection. A failed test pinpoints the broken service before you dig into logs.

  4. Check the Odoo server logs — look for ERROR sadeem.cloud lines around the time of the failure. Python tracebacks here often reveal misconfiguration that the UI error message summarises only briefly.

  5. Verify the subscription state — some action buttons are only available in specific states. If a button is missing, check whether the subscription is in the expected state and use the status bar to confirm.

Diagnosis & Fix runs in the background

Diagnosis & Fix was introduced to avoid HTTP timeouts on slow infrastructure. When you click the button, Sadeem enqueues a background job and returns immediately — the button does not block. The detailed HTML report appears in the chatter once the job completes, typically within 10–60 seconds. The same tool is available on individual stages from the stage list.