Troubleshooting
A short list of symptoms a new install hits on day one. If none match, the platform’s logs (configured via the Serilog section of appsettings.yaml) are the next stop — they include the operator pack load order at startup, which usually tells you what is missing.
| Symptom | What to check |
|---|---|
| Connection refused on port 5000 | The service is not running, or it bound to a different port. zen service status (or journalctl -u zenvara on Linux) tells you which. Reconfigure via Kestrel:Endpoints:Http:Url in appsettings.user.yaml. |
503 from /api/v1/platform/diagnostics | The platform is up but not yet ready — usually because operator extensions are still loading or the storage directory is unreachable. Wait 5–10 seconds, then check the logs. |
| ”Operator not found” when invoking a flow | The operator pack is missing from extensions/. From-source builds lay these out automatically; for published binaries, verify the artifact was extracted with the extensions/ directory intact. |
| 401 / 403 on every request | Authentication is enabled but no credential was supplied. Either disable auth for an evaluation (Auth.Enabled: false) or configure an API key. See Authentication. |
| Storage permission denied (Linux/macOS) | The service account does not own Storage.Directory. chown -R zenvara:zenvara /var/lib/zenvara and restart. |
| Flow file edits do not take effect | The flow’s status: field is inactive, or the file is in the wrong directory. Verify it lives under {Storage.Directory}/flows/{name}/definition.yaml. |
| Git working-tree ownership error on Windows | With Git versioning on, the data/versions tree is owned by the service account; libgit2 refuses to open it from a different user. Launch the binary as the service account (runas /user:.\SvcZenvara cmd). See Deployment Targets. |
Getting unstuck while authoring
Section titled “Getting unstuck while authoring”Most flow-authoring problems are faster to solve with an AI assistant than a search engine. An MCP-aware client (Claude Code, VS Code with the Zenvara MCP server, or any MCP host) sees the live operator catalog, the type provider’s signatures, and your installation’s actual error messages. Paste the failing YAML and the diagnostic and ask “what’s wrong with this flow?” — the assistant can usually answer in one round-trip, and can run small experiments against your install as part of the diagnosis.
Reporting bugs and requesting features
Section titled “Reporting bugs and requesting features”If a problem turns out to be a real bug, report it through the built-in channels rather than informal email — both attach your installation’s environment fingerprint and land in the triage queue automatically:
submit-support-request(MCP) orPOST /api/v1/platform/support(REST) — for problems and questions.submit-feature-request(MCP) orPOST /api/v1/platform/support/feature-request(REST) — for missing capabilities.
See the full Error Catalog for diagnostic codes.