Skip to main content
First confirm that the authoritative runtime is still running and that the current project and workspace are correct, then look at the structured error code and the latest timeline event. Do not post complete logs to a public issue; see the redaction checklist at the end.

​
Common error codes

Vibex reports failures as structured error codes, shown in the UI as error code: description. The common ones are:

​
Remote and pairing

​
Sessions and workspaces

​
Files and Git

​
Configuration and releases

If your problem is not in these tables, include the complete error code string in your issue—it is the key to diagnosing the problem.

​
An Agent will not start or is unavailable

  1. Open Config Center → Agent and confirm the Agent’s status is not Disabled.
  2. If the status is Not installed, click Install; if it is Managed by user, confirm the corresponding command-line program is on PATH and executable.
  3. Expand Native credentials and check the sign-in state; use Re-authenticate if needed.
  4. Expand Model provider configuration, confirm a model is configured, and use Test connection to verify connectivity.
  5. Run the Agent’s version command directly in a terminal to confirm PATH and permissions are fine.

​
A message is stuck or its state looks wrong

  • Check whether the timeline is waiting on a permission request or an elicitation for you to handle.
  • Confirm no other run is occupying the same workspace.
  • Right after the app restarts, wait for persisted state to finish loading.
  • If a session shows running but no process exists, restart the authoritative runtime once so it re-detects state.
running is only the last observed state; it does not mean the process is still alive. Do not resend commands that have side effects because of it.

​
File or Git results are wrong

  • Confirm the current project and workspace. Local and Worktree are different directories, and editing the wrong one is a common mistake.
  • Save the editor file before refreshing the file tree and Git status.
  • Check for external modifications or merge conflicts.
  • Before revert, amend, push, or deleting a worktree, read the diff and create a recovery point.

​
The terminal shows no output

Check whether the tab is bound to the right workspace, whether the PTY is marked stale, and whether the shell has exited. Resize the panel or reopen the tab, and trust the new terminal snapshot. Vibex’s terminal scrollback buffer is fixed at 10000 lines; earlier output has already been discarded, so rerun the command if you need it.

​
Preview will not open

​
The desktop cannot connect to a self-hosted runtime

  1. On the server, confirm that curl -fsS http://127.0.0.1:8765/api/v2/info responds.
  2. Confirm VIBEX_PUBLIC_HOST is an address the client can actually dial, including the port.
  3. Local network mode requires VIBEX_TLS_MODE=pinned_certificate, and you must pair from the connection string (which carries the certificate); entering the address by hand fails for lack of the certificate.
  4. In public mode, confirm VIBEX_ALLOWED_HOSTS contains the domain actually being used, or the gateway returns 421.
  5. Check the tls_fingerprint in the server log and compare it with the Certificate line shown by the client.

​
The phone cannot connect

  1. Confirm the authoritative runtime is running and that a connection method is enabled (Tailscale Serve / Direct HTTPS / Self-hosted Relay / Local network pairing).
  2. Check the network between the phone and the authority; if Direct fails, try Tailnet or Relay.
  3. Generate a new QR code or connection string; do not reuse old pairing credentials.
  4. When revoked appears, you must pair again; when resync_required appears, wait for the authority to finish synchronizing.
  5. When using Relay, check /health and /api/info—and note that Relay has no /api/v2/info.

​
Submitting diagnostics

Please provide:
  • The Vibex version and release channel (see Settings → About)
  • Your operating system and version
  • Steps to reproduce
  • The structured error code (the most important part)
  • Redacted timestamps
Before submitting, remove: tokens, private keys, pairing codes, connection strings, workspace paths, prompts, file contents, Git diffs, and terminal output. Issue tracker: GitHub Issues.