Troubleshooting

Known issues and workarounds. For Linux-specific problems, see Linux troubleshooting.

Utilities not found in PATH

If Devsy Desktop cannot find tools such as docker in your PATH, start it through your shell. On macOS:

#!/usr/bin/env sh
exec "$SHELL" -lic 'exec /Applications/Devsy.app/Contents/MacOS/Devsy'

Port forwarding does not work without an IDE

Port forwarding needs an open SSH session. With --ide none, keep one open with devsy workspace ssh WORKSPACE_NAME. Ports declared in Docker Compose do not need it.

Reading CLI errors

Pass --log-output json to get errors as JSON with a stable code and a message. Some errors also include a hint and a context object.

{
  "code": "UNKNOWN",
  "message": "exit status 1: something failed"
}

Code	Meaning
`RATE_LIMITED`	An upstream API rate-limited the request. Wait and retry, or authenticate.
`BUILD_FAILED_RECOVERABLE`	The devcontainer build failed in a way that can be retried, for example with `--recovery`.
`docker_daemon_unreachable`	Docker is not running or not reachable.
`canceled`	The operation was canceled.
`deadline_exceeded`	The operation timed out.
`unlock_required`, `unlock_failed`	The secrets store is locked, or unlocking it failed.
`secret_backend_unavailable`	The secrets backend could not be reached.
`secret_store_corrupt`	The secrets store could not be read.
`secret_not_found`	The requested secret does not exist.
`PANIC`	Devsy hit an internal error. Please report it.
`UNKNOWN`	The error was not classified. The original text is in `message`.

Run with --debug to see the full error chain.

VS Code-family editor launch diagnostics

For VS Code, VSCodium, and related editors, a failed CLI launch records the flavor, operation, route, failed stage, and failure class (for example, exit status 1 or permission denied). A successful URI-handler fallback does not erase that CLI warning. With --debug, the logs also record executable resolution, extension enumeration/installation, and dispatch stages. Use the same operation value to correlate these records within the workspace task's logs; it comes from the active IDE-launch status operation.

Executable paths, command arguments, folder URIs, editor output, and underlying error text are deliberately omitted from these diagnostics because they may contain private paths, host names, or credentials that cannot be reliably redacted. Failure classes and stage names remain available; callers can inspect the original errors programmatically. The resolved file's cli_kind identifies an executable or batch-wrapper filename, not proof that a Windows wrapper ran.

"Launch request dispatched" means the editor CLI or OS URI handler accepted the request. It does not prove that the editor stayed running or connected over SSH. If the editor closes or does not connect, collect its own logs separately and review them for private data before sharing.

Windows: `line 2: $'\r': command not found`

Windows line endings break shell scripts inside the container. Add this to .gitattributes:

*.sh eol=lf

Neovim: `$TERM` issues over SSH

See issue #1187 for a workaround.

Troubleshooting

Utilities not found in PATHCopy Anchor Link

Port forwarding does not work without an IDECopy Anchor Link

Reading CLI errorsCopy Anchor Link

VS Code-family editor launch diagnosticsCopy Anchor Link

Windows: line 2: $'\r': command not foundCopy Anchor Link