Troubleshooting
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 -c '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.
Windows: line 2: $'\r': command not found
Windows line endings break shell scripts inside the container. Add this to .gitattributes:
*.sh eol=lfNeovim: $TERM issues over SSH
See issue #1187 for a workaround.