Find your fix.
A practical troubleshooting guide for PENTER Desktop. Search by the exact error message, choose the feature that isn't working and follow safe, step-by-step fixes.
Search common issues
InstallationWindows displays a publisher or SmartScreen warning
The beta installer is unsigned; a Windows trust warning is possible even with an intact download.
Windows displays a publisher or SmartScreen warning
The beta installer is unsigned; a Windows trust warning is possible even with an intact download.
Steps to fix
- 01Confirm you downloaded the installer from the official PENTER Download page and its linked public release.
- 02Compare the SHA-256 with the checksum on the release page before deciding whether to continue.
- 03If Windows Security identifies an actual threat, stop and report it. Do not disable Defender or add broad antivirus exclusions.
InstallationPENTER does not open, or closes immediately
A first launch exits or the Desktop window never appears.
PENTER does not open, or closes immediately
A first launch exits or the Desktop window never appears.
Steps to fix
- 01Check that this is the Windows x64 installer rather than a source-code archive.
- 02Restart Windows and retry once after closing any existing PENTER process.
- 03Check the Windows Security protection history for a specific blocked executable rather than disabling protections.
- 04If it still fails, record the version, Windows build, exact error, and whether the window ever opened.
AccountDevice code expired or approval does not complete
The Desktop authorization code has timed out, or the website and Desktop are using different accounts.
Device code expired or approval does not complete
The Desktop authorization code has timed out, or the website and Desktop are using different accounts.
Steps to fix
- 01Request a new device code in Desktop and use the current code only.
- 02Sign in to penter.dev with the account that should own this PC.
- 03Check the code shown by Desktop before approving the request on the website.
- 04If the device was revoked, start a new authorization instead of reusing the old token.
AccountLogin or MFA is failing
A login, multi-factor step, or device security challenge fails.
Login or MFA is failing
A login, multi-factor step, or device security challenge fails.
Steps to fix
- 01Confirm that you are using the correct account and a current authenticator code when MFA is enabled.
- 02Check the device clock and retry a fresh sign-in rather than repeatedly reusing an expired challenge.
- 03Use the password-reset flow if you cannot sign in. Never send passwords, recovery codes, session tokens or API keys with a support report.
Agent & AIThe model returns an error or is unavailable
Cloud provider errors, insufficient credits, rate limits, or an offline local model.
The model returns an error or is unavailable
Cloud provider errors, insufficient credits, rate limits, or an offline local model.
Steps to fix
- 01Check whether the failure affects one selected model or all models.
- 02For Cloud AI, verify your PENTER account/device authorization and available usage in the dashboard.
- 03For an Ollama/local provider, confirm the model and server work independently on this machine.
- 04Record the exact error or request ID (without credentials) instead of repeatedly submitting the same request.
Agent & AIThe agent stops after one action or has no tool results
The conversation returns a conclusion without the expected investigation evidence.
The agent stops after one action or has no tool results
The conversation returns a conclusion without the expected investigation evidence.
Steps to fix
- 01Check the execution timeline for a real tool request and result. A model description is not proof a command ran.
- 02Confirm that the engagement scope and the chosen Browser/HTTP capability are available.
- 03Ask for a bounded multi-step investigation that verifies findings and explicitly reports blocked steps.
- 04If an execution surface is blocked by beta policy, do not attempt to bypass it through another tool.
BrowserBrowser Agent cannot start on first use
Managed Chromium is missing or its first-use download failed.
Browser Agent cannot start on first use
Managed Chromium is missing or its first-use download failed.
Steps to fix
- 01Allow the prompted, first-run managed Chromium download.
- 02Verify that your network can reach the Playwright browser-download CDN.
- 03Retry from inside Desktop and check the explicit error if it still fails.
- 04Do not copy a browser executable from an untrusted website into PENTER.
BrowserNavigation is blocked or page actions stop working
The browser rejects a different target, or a selector becomes stale after navigation.
Navigation is blocked or page actions stop working
The browser rejects a different target, or a selector becomes stale after navigation.
Steps to fix
- 01Confirm that the current workspace is bound to the intended authorized target.
- 02Start a new engagement when changing to a different customer or scope.
- 03Refresh the page snapshot/elements after navigation and select the new element.
- 04Redirects, popups and WebSocket connections may be restricted in the beta; do not treat a blocked out-of-scope URL as a broken browser.
DockerDocker pipe not found / cannot connect to Docker Engine
open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.
Docker pipe not found / cannot connect to Docker Engine
open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.
Steps to fix
- 01Open Docker Desktop and confirm its Linux engine reports Running.
- 02Check the active context. On a normal Docker Desktop/WSL2 setup it should be desktop-linux.
- 03Test the engine with docker info and expect linux before retrying PENTER.
- 04If the pipe remains missing, check Docker Desktop status and the WSL 2 backend before restarting Docker Desktop.
- 05A stopped com.docker.service is not by itself proof of failure when the WSL 2 backend and Linux engine are working.
docker context ls
docker context use desktop-linux
docker info --format "{{.OSType}}"
wsl --status
wsl -l -vDockerA Docker image is missing or cannot be used
PENTER cannot find the approved image on the selected local Docker Engine.
A Docker image is missing or cannot be used
PENTER cannot find the approved image on the selected local Docker Engine.
Steps to fix
- 01Ensure Docker Desktop is running in Linux-container mode.
- 02Download only an image you trust, using PENTER Settings → Docker or the Docker CLI.
- 03Select the image in PENTER and keep networking set to none for the packaged beta.
- 04An offline managed container cannot access the internet to install tools while it runs.
docker info --format "{{.OSType}}"
docker pull alpine:3.21
docker image lsBeta limitsWSL/Kali, native shell, MCP or networked Docker is blocked
Unconfined execution is intentionally disabled in the packaged public beta.
WSL/Kali, native shell, MCP or networked Docker is blocked
Unconfined execution is intentionally disabled in the packaged public beta.
Steps to fix
- 01This is a security limitation, not an installation failure. Native shell, WSL/Kali commands and MCP process/tool execution are blocked in packaged builds.
- 02Docker execution is available only with network=none. Docker Compose up and remote Desktop Relay execution are also disabled.
- 03For target-facing investigations, use the approved scoped Browser, HTTP and Request Lab surfaces.
- 04Do not disable protection or switch to a development build to bypass an authorization boundary.
Beta limitsCloud command execution or checkout returns unavailable
CLOUD_EXECUTION_UNAVAILABLE, HTTP 503, or checkout disabled during the beta.
Cloud command execution or checkout returns unavailable
CLOUD_EXECUTION_UNAVAILABLE, HTTP 503, or checkout disabled during the beta.
Steps to fix
- 01Cloud command execution and paid checkout remain server-side disabled until their release gates pass.
- 02Cloud AI chat is a separate capability; check its account/model error independently.
- 03Use the supported scoped local Desktop tools for authorized testing; do not treat a 503 gate as a configuration problem on your PC.
InstallationAutomatic updates are not installing
The beta only checks for updates; silent download and auto-install are disabled.
Automatic updates are not installing
The beta only checks for updates; silent download and auto-install are disabled.
Steps to fix
- 01The packaged Windows application can check the configured release feed, but beta builds do not auto-download or auto-install.
- 02The update feed may return unavailable until the beta channel is enabled.
- 03When a verified new release is published, use the official Download page and compare its version and SHA-256.
Still stuck? Note your PENTER and Windows versions and exact error. Remove API keys, tokens, browser cookies and customer data before sharing logs.
Check the basics first
Account and device problems
What to share if the issue remains
Note your PENTER Desktop version, Windows version, the feature you were using and the exact error text. Explain which steps you already tried. That gives support useful context without collecting your engagement data.
New to PENTER? Follow the setup guide from the beginning.
Ready to get started?
Follow the setup guide, install the current approved Desktop release, and connect your account.