Troubleshooting
Where to look when flows fail
Start with the stable identifier visible to the customer: email plus subscription, HOSTING-NNNNN, MIG-NNNNN or Studio workspace ID. Follow that identifier across layers instead of searching all logs for generic text.
Log locations
| Symptom | First places to inspect |
|---|---|
| Portal UI/API error | mivama-portal.service journal, browser network response, Frappe web/error log |
| Checkout or missing invoice | Mivama Stripe Event/Subscription/Invoice, Stripe event delivery, Frappe scheduler journal |
| Hosting not created | subscription mirror, Hosting Service, provisioning jobs, runner journal |
| Ansible failure | runner structured result, playbook task, tenant Compose logs |
| Migration connect/upload | migration record/events, gateway journal, connector technical details |
| Migration import/cutover | migration worker journal, target Compose/WordPress health, rollback result |
| Studio sync/deploy | Studio web and worker journals, workspace/job/event records, live fingerprint |
| Email missing | Frappe Email Queue, recipient language/preferences, SMTP response |
| Public 404/TLS | Nginx selected vhost, upstream status, certificate and WordPress rewrite rules |
Common failures
DocType not found
The Mivama Core schema has not been migrated on the active Frappe site or the wrong site is being queried. Confirm apps.txt and run the reviewed bench migration. Do not catch and ignore it in Portal.
String and integer TypeError
Frappe values and form data may arrive as strings. Normalize at the API boundary with explicit conversion before comparisons. Preserve null/empty semantics and validate ranges.
HTTP 401 after connector connection
The one-time code was already exchanged and must not authenticate later calls. Confirm the plugin persisted the scoped migration token and sends it to the correct endpoint. Check token hash, migration identity, expiry and disconnect state.
Migration state conflict
Read current status, requested operation and last event. Do not force the status. Finish/retry the missing upload/import/review transition.
WordPress CLI refuses root
This is a correct safety guard. Execute as the tenant WordPress/container user. Adding allow-root would run customer code with host authority and produce wrong ownership.
Docker address pools exhausted
Studio Compose projects previously created a new Docker network per workspace until all default subnets were consumed. Reclaim only verified orphan networks and use an explicitly managed address pool/network strategy. Never delete active tenant networks by broad name matching.
Site stuck in migration maintenance
Inspect migration final-sync state and the target maintenance marker. Only the worker that owns the phase should clear it after success/rollback. A reconciler may repair a stale marker after proving no active final-sync job exists.
Subdirectory pages return Apache 404
Confirm WordPress home/siteurl after migration, generated rewrite rules, Apache rewrite module and AllowOverride settings. The migration worker must flush rewrites and preserve .htaccess ownership. The fix belongs in the import/provisioning path so future sites inherit it.
Safe incident response
Capture identifiers and timestamps, stop only the narrow job/service causing harm, preserve logs and backups, repair source-of-truth state or idempotent automation, then verify. Avoid manual database status edits, broad Docker cleanup, recursive permission changes or deletion based on unresolved variables.