Troubleshooting

Symptom	Check
Connection refused on localhost	Listener enabled, correct port, desktop background service running; container localhost is not the host.
401	Correct destination token, Bearer header, expiry and revocation.
403	Scopes, resource grant, workspace membership, active API/logging entitlement.
404	Base URL, route, workspace/resource UUIDs, and destination resource existence.
400 or 422	JSON syntax, endpoint-specific fields, timestamp timezone, supported severity, and schema constraints.
409	Read the returned error: revision/idempotency conflicts and admission conflicts require different recovery.
413	Reduce batch size; compressed and decompressed limits both apply.
429	Respect Retry-After and inspect quota/usage; use bounded backoff.
5xx or timeout	Retry with backoff; a timed-out write may already have succeeded.
Accepted logs are absent	Correct destination/resource, separate read permission, filters, retention, and forwarding status.
Desktop forwarding paused	Correct cloud URL/key, then use Retry. Full queues can skip additional cloud copies.

Browser / server preview

• Run server-setup before starting the server: finish owner setup first. On Windows, scripts/start-server.ps1 handles setup and startup together. server-setup is a Python CLI subcommand, not a PowerShell executable.
• Passwords do not match: retry both hidden prompts with the same password of at least 12 characters. Don't type the password after the normal PS ...> prompt.
• Connection refused: keep the server process running, include its port (default 43120) in the URL, and keep your SSH tunnel open if you use one.
• Cross-site request denied after portal consent: update older preview builds and reopen the configured app URL. Check whether the connection already completed before reconnecting. Keep origin and CSRF checks enabled.
• 401 from /auth/session before login: sign in with the server owner password. MCP clients instead need a server-issued bearer token.
• Untrusted host or origin: use exactly the scheme, host, and port configured by --base-url; switching between localhost and 127.0.0.1 changes the origin.

Browser extension messages about vaults, device trust, or native app integration may come from a password manager. Find the failing request to your Alshitask origin and its response rather than assuming every console message belongs to the app. See server setup for the complete commands.

Collect useful diagnostics

Record HTTP status, response error code/message, request ID when returned, timestamp with timezone, route, and destination. Redact tokens, cookies, payload secrets, and personal data before sharing diagnostics. Cloud and local error envelopes may differ; inspect the response rather than assuming one format for every endpoint.

Use the live cloud reference to check deployed behavior. Documentation's schema snapshot records the reference used for this publication.

---

Published from the versioned Alshival documentation source. Edit the source rather than this generated page.