Troubleshooting

The three problems that bite first-time users on day one, and how to fix each. If your symptom is not listed, open an issue at github.com/Riiquezz/vuptdev/issues with the failing command, the output, and your OS — the maintainers respond within 24h on weekdays.

PTY agent install failures

Every agent (Claude Code CLI, Codex CLI, Cursor CLI, Aider, Cline, OpenCode) runs inside a pseudo-terminal (PTY) that Vupt allocates per task. PTY allocation is the most common failure surface because it touches OS-specific kernel APIs.

Windows 11

Symptom: PTY allocation failed: ConPTY not available in the task journal, agent never starts.

Root cause: Windows ConPTY requires Windows 10 build 17763 or later. Windows 11 always meets this, but the failure surfaces when the Vupt binary lacks the conhost.exe co-host or when a Group Policy disables Win32 console allocation.

Fix (try in order):

1. Re-run the installer as Administrator once — this re-registers the conhost.exe association under HKLM instead of HKCU, which some corporate Group Policies require.

2. Check whether conhost.exe is on PATH:

   Get-Command conhost.exe

   If missing, your IT department has disabled it. Ask them to allowlist %WINDIR%\System32\conhost.exe for the Vupt process.

3. Fallback: enable WSL2 and run agents inside the Linux subsystem. Set defaults.pty_backend = "wsl" in ~/.vupt/config.toml and restart Vupt.

macOS

Symptom: Gatekeeper blocks the bundled agent binary on first run: "vupt-pty-helper cannot be opened because the developer cannot be verified".

Root cause: Vupt's bundled agents are signed and notarized, but Gatekeeper still prompts the first time a binary is invoked from outside /Applications. The notarization ticket sometimes does not propagate to nested binaries inside the .app bundle.

Fix:

1. Open System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway next to the blocked binary message.

2. If no message is shown (Gatekeeper silently killed the process), invoke the helper manually once from Terminal:

   /Applications/Vupt.app/Contents/Resources/agents/vupt-pty-helper --version

   Gatekeeper will prompt, and once you accept, the binary is whitelisted for all future invocations.

3. If you are on macOS 15 (Sequoia) or later, you may also need to grant Vupt Full Disk Access under Privacy & Security → Full Disk Access so the PTY can write task journals to ~/.vupt/.

Linux

Symptom: posix_openpt: Permission denied or PTY allocation failed: locale not supported.

Root cause: Either /dev/ptmx is not world-writable (uncommon, but happens on hardened distros like Alpine), or the requested locale is missing.

Fix:

1. Confirm /dev/ptmx permissions:

   ls -l /dev/ptmx
   # expected: crw-rw-rw- 1 root tty 5, 2

   If not crw-rw-rw-, your distro is locked down. Add your user to the tty group:

   sudo usermod -aG tty $USER
   newgrp tty

2. Install the locale Vupt requested (defaults to en_US.UTF-8; pt-BR users may need pt_BR.UTF-8):

   sudo locale-gen en_US.UTF-8 pt_BR.UTF-8
   sudo update-locale

3. If the agent's own binary (Codex CLI, Aider, etc.) was installed separately via pip install or npm install -g, re-run the install with the same $PATH that Vupt sees. The simplest check:

   /Applications/Vupt.app/Contents/MacOS/vupt --print-env | grep PATH
   # then on Linux:
   /opt/vupt/vupt --print-env | grep PATH

   Match that PATH when installing the agent.

Sandbox connection issues

The public sandbox at demo.vupt.dev is currently in maintenance — Vupt v1.3 ships an interim Request access to sandbox landing instead (see /sandbox-request). The notes below cover both the public-sandbox path (when it returns in v1.4) and the local-sandbox path (available now via the desktop app).

Public sandbox returns 502 or NXDOMAIN

Symptom: demo.vupt.dev returns Bad Gateway or fails DNS resolution.

Fix:

1. Check the status page at status.vupt.dev. If sandbox is reported as in maintenance, use the /sandbox-request form to request scheduled access.

2. While public sandbox is unavailable, run your own local sandbox via the desktop app: open Vupt, create a new project pointing at a scratch git repo, and use the Try sample squad template (Settings → Templates → Sample squad). This gives you the same end-to-end flow (squad creation → parallel agents → diff review) on your own machine.

Session create times out (more than 2s)

Symptom: Sandbox loads, but creating a new session hangs past the 2s SLA.

Fix:

1. Cold-start warm-up: the sandbox container scales to zero overnight. Refresh after 30s and the warm container handles the next request in under 500ms.

2. If the timeout persists past 2 minutes, the sandbox provisioner is under load. Try again at off-peak hours (BR business hours are 09:00–18:00 BRT) or use the local-sandbox path above.

Cross-session data appears (someone else's squad shows in your view)

Symptom: You see a squad you didn't create — or your data disappears between page reloads.

Root cause: Sandbox uses a daily-reset cron and ephemeral session cookies. If you opened the sandbox in two browser tabs or had a stale cookie from a prior day, the session pointer can desync.

Fix:

1. Clear cookies for demo.vupt.dev and reload.

2. Open an incognito / private window and re-run your test there.

3. Sandbox state is wiped at 00:00 UTC every day — bookmark any squad output before then or it will not survive the reset.

BYOK key paste errors

BYOK (Bring Your Own Key) is how every paid provider is configured — Vupt stores the key in your OS keychain and only persists a reference (e.g. vupt/anthropic) in ~/.vupt/config.toml. The keychain itself is the source of truth, not the config file. See Configuration for the full key reference.

Key with trailing whitespace silently fails

Symptom: Provider returns 401 Unauthorized even though the key is correct.

Root cause: Copying from a terminal or a PDF often appends a newline or U+00A0 non-breaking space. Most providers' API gateways treat the whitespace as part of the key and reject it.

Fix:

1. Use the Validate Key button in Settings → Providers — it trims whitespace before storing and pings the provider's /v1/models endpoint to confirm.

2. If you must paste manually, normalize first:

   # macOS / Linux — trim whitespace
   pbpaste | tr -d '[:space:]' | pbcopy

   # Windows
   Get-Clipboard | ForEach-Object { $_.Trim() } | Set-Clipboard

3. After paste, the UI shows the key's last 4 characters. If the count is off by 1, you pasted whitespace.

Key entered into wrong provider field

Symptom: The agent fails to authenticate with Invalid API key but the key is genuinely valid.

Root cause: Vupt has one key field per provider, and they look similar. A Claude Code key (prefix sk-ant-) pasted into the Codex field (which expects prefix sk-) will fail because the OpenAI gateway rejects the sk-ant- prefix.

Fix: Re-check the provider headers in Settings → Providers:

Provider	Key prefix
Claude Code (Anthropic)	sk-ant-
Codex (OpenAI)	sk-
Cursor CLI	csk-
Aider (any LLM gateway)	varies — match the provider you point Aider at

Key revoked by provider

Symptom: Was working yesterday, now returns 401 across all attempts.

Root cause: The provider rotated or revoked the key. This happens on a security incident or when you log into a new device.

Fix:

1. Visit the provider's API dashboard:

   • Anthropic: console.anthropic.com/settings/keys
   • OpenAI: platform.openai.com/api-keys
   • Cursor: cursor.com/settings/api

2. Generate a fresh key and replace the keychain entry in Settings → Providers → Edit → Replace key. The keychain entry is the only place Vupt reads from at runtime; replacing it does not require a restart.

3. If the provider revokes for unusual usage patterns, audit your task journal for any prompt that may have triggered the provider's safety filters (e.g. requests to scrape user data). Vupt does not silently retry blocked prompts — the failure is in the journal verbatim.

Still stuck

• Open an issue: github.com/Riiquezz/vuptdev/issues (24h response on weekdays)
• Status page: status.vupt.dev
• Discord (BR/LatAm time zones): see the link in the desktop app footer