Troubleshooting · Docs

Desktop client won't start

Three causes account for almost every cold-start failure. The launcher logs the reason to

~/Library/Logs/Velocity/launch.log

(macOS) or

%LOCALAPPDATA%\Velocity\Logs\launch.log

(Windows). Open it first; the message is usually one of the following.

License expired or invalid signature. Self-hosted only. Your Ed25519-signed license blob has lapsed or been edited. Get a fresh key from the portal and replace the file at
```
/etc/velocity/license.key
```
.
Code OSS extension SHA mismatch. A bundled extension hash failed verification — almost always because antivirus or DLP quarantined a file. Reinstall the client; if it repeats, allowlist the install directory in your endpoint protection.
KEK env missing. Self-hosted backend cannot derive session keys without the
```
VELOCITY_KEK
```
environment variable. Set it in your systemd unit or container env and restart.

Session keeps going idle

Sessions auto-suspend after a configurable idle window to free cloud compute. If yours is dropping faster than expected, the org policy is set low.

Open the desktop client and click your org avatar → Org Settings.
Navigate to Security and find
```
session_timeout_minutes
```
.
Raise it (default is 30, max is 480) and save. The change applies to new sessions immediately.

Login refused — "pending_payment"

The backend returns

pending_payment

when Stripe reports the org's subscription as past_due or unpaid. This usually means a card expired and the retry schedule has run out.

Manager opens the portal at
```
aethernaut.ai/portal/billing
```
.
Click Manage in Stripe to open the Customer Portal.
Update the card or pay the open invoice. Stripe fires a webhook within seconds.
The backend flips the org back to
```
active
```
; users can sign in immediately.

If the webhook is delayed (rare), Admins can force a refresh from the admin panel underBilling → Sync from Stripe.

Can't push a build for review

The Build tab grays out the submit button when the backend would reject the request. The two common causes are project membership and role.

Not in
project_members
. Even Admins must be added to a project to push builds. Have the project's Admin add you under Project Settings → People.
Wrong role. Only Developers and Admins can submit builds. Reviewers approve, they don't push. The Manager role can't push code at all.

AI authorship paint stuck on

The hot-pink AI authorship highlight occasionally fails to clear after a long CLI session. It's a renderer state issue in the extension, not a data issue — the underlying authorship metadata is correct.

Press
```
Cmd+Shift+P
```
(macOS) or
```
Ctrl+Shift+P
```
(Windows).
Run Velocity: Reload AI Authorship.
The decorations are rebuilt from the authorship log in under a second.

Loro op log diverged

Very rare. If a long-running session shows a banner reading op log diverged — resyncing, the client detected a CRDT state that doesn't match the server snapshot. Restart the session; the client discards its local op buffer and rehydrates from the authoritative server snapshot. No work is lost because every committed op was already on the server.

GDPR export stuck at "preparing"

User-initiated GDPR exports queue a backend job that bundles the user's audit rows, messages, and authorship records into an encrypted zip. The status moves preparing →ready when the admin panel acknowledges the artifact.

Admin opens the admin panel → Compliance → GDPR Requests.
Find the request and click Mark Ready, which POSTs to the mark-ready endpoint.
The user receives an email with a 7-day download link.

If the request has been preparing for more than an hour, file a support ticket — the job worker may have crashed and needs a manual nudge.