Chapter 18 — Troubleshooting & FAQ

A symptom-first lookup. Each entry starts with what you actually see on screen (or what is missing), then explains what to try in order from cheapest to most invasive. If nothing in here works, the bottom of the chapter explains how to file a useful bug report.

Use Ctrl+F on this page to jump straight to your symptom. Entries are grouped by where the symptom shows up, not by the underlying subsystem.

How to use this chapter

1. Look up the symptom in the table of contents or with Ctrl+F.
2. Try the fixes in order. Each list is sorted cheapest-first; if step 1 works, you do not need step 2.
3. If still broken, the relevant chapter has deeper context — every entry cross-links to it.
4. If it looks like a bug, jump to Filing a useful bug report at the bottom.

Contents

• Launch and login
• SSH and connections
• File browser, editor, save
• LCOT panel
• Fleet Manager and OTA
• Network tools
• Security tools
• AI Assistant and Hierarchy Builder
• Cameras
• Databases
• Settings, themes, layout
• Updates and licensing
• Performance
• Diagnostics you can run yourself
• Filing a useful bug report

Launch and login

AidaIDE will not launch at all

1. Launch from a terminal so you can see startup errors: aidaide on Linux/macOS, "C:\Program Files\AidaIDE\aidaide.exe" on Windows.
2. Try safe mode: aidaide --safe-mode. This skips plugins and uses default settings. If safe mode works, the culprit is a plugin or a custom theme — disable them one at a time.
3. If safe mode also fails, capture ~/.aidaide/logs/aidaide.log and file a bug from another machine. See also Ch. 17 §"AidaIDE will not start after an update".

Login window appears but typing does nothing

The Smart Login window owns keyboard focus on launch. If it does not:

1. Click directly on the password field.
2. If you have a non-English keyboard layout and the field stays blank, swap input methods (Win+Space on Windows; some IMEs swallow the keystrokes).
3. As a last resort, close (X) and relaunch; the focus bug is timing-related.

"Vault Locked" but I never set a master password

You did, on a previous install. The vault file at %APPDATA%\AidaIDE\ (Windows) or ~/.aidaide/ (Linux/macOS) survives uninstalls. Either:

• Remember and enter the password, or
• Click Forgot password? Reset vault under the password field. This wipes every saved secret. See Ch. 1 §Unlocking the vault.

Splash plays forever / window never appears

Background loading is stuck. Wait 30 seconds; if still hung:

1. Skip the splash next launch: set AIDA_SPLASH=off as an environment variable.
2. Kill the process and relaunch.
3. If it recurs, capture the log — startup tasks are time-stamped there.

"Soft restart" — login skipped, did something change?

By design — see Ch. 1 §Soft-restart bypass. To force a password prompt next launch, File → Exit explicitly.

SSH and connections

"Connection refused" or "Connection timed out"

The single most common cause is a wrong port. AidaIDE has historically had a few callsites that hardcode port 22:

1. Re-open the host in Connection Manager and verify Port is set to your server's listening port.
2. Test from a real terminal: ssh -p <port> user@host. If that fails too, the problem is the server or network, not AidaIDE.
3. Check that the device is reachable: ping host.
4. If you can SSH from a terminal but AidaIDE cannot, file a bug and attach ~/.aidaide/logs/ssh.log — that is the port-22 trap resurfacing. See Ch. 2 §Ports and the port-22 trap.

"Host key has changed!"

Genuine security feature. Either:

• The server was reinstalled / rekeyed (benign — verify with the server admin, then click Accept New Key).
• Someone is intercepting your traffic (do not accept; contact whoever runs the server).

See Ch. 2 §Host key.

"Permission denied (publickey)"

1. Connection Manager → host → Authentication. Is the right key file selected? It should point at the private key, not .pub.
2. On the server, verify ~/.ssh/authorized_keys contains the matching public key.
3. Check permissions on the server: chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys.
4. On Windows, the private key file itself must be readable only by your user — see Ch. 2 §Key permissions errors.

Save to a remote file appears to succeed but the file did not change

A legacy bug: silent fall-through from SFTP to local open(). Should be fixed.

1. Reopen the file from the remote tree (not from Recent Files) to confirm.
2. Check ~/.aidaide/logs/ssh.log for an SFTP error around the save time.
3. If the local-file mirror is being edited, the tab title shows the local path; if it is the remote, the title is prefixed with the host name. See Ch. 2 §Edit a remote file.

A password field mysteriously goes blank

The vault decrypt step failed silently in the past. Should now surface as an error dialog.

1. Re-enter the password in Connection Manager and Save.
2. If the field blanks again on next launch, file a bug — that is a recurrence and we need the log.

"I just changed my SSH port and now nothing connects"

1. Update the Port in every Connection Manager entry pointing at that host.
2. If you have devices in Fleet Manager, update device.ssh_port there too.
3. Restart any open connection tabs (they cache the port for the session).

Drag-and-drop upload silently does nothing

1. Confirm the destination pane has focus (click into the remote tree first).
2. Check the status bar — uploads show a progress line there.
3. Look at ~/.aidaide/logs/ssh.log — SFTP permission errors usually mean the remote user cannot write to the target directory.

File browser, editor, save

Editor will not show a file even though it opens

Check the file size; very large logs trigger AidaIDE's read cap. There is no unbounded read by design.

• Open with tail -n 5000 logfile | nl in the terminal pane instead.
• Or use Find in Files scoped to the directory.

See Ch. 3 — File Browser and Editor.

Find in Files returns wrong file names

Older bug: result-click was stripping the directory and opening the wrong file. Re-test after updating; if it still happens, file a bug with the search term, the result list, and which file actually opened.

Auto-save did nothing

Settings → Editor → Behaviour → Auto-save has three modes: Off, On Focus Change, On Idle (delay). If you expected to see changes on disk, check that the mode you expected is selected. See Ch. 13 §Behaviour.

Ctrl+S re-prompts Save As… every time

You opened the file from File → Recent Files when its path was unknown (legacy bug). Work around by closing and reopening from the file tree. If it recurs on freshly opened files, that is a bug — capture the log.

Split-pane editor: second pane has stale status bar / no lint

Known issue with the secondary editor pane in some builds. The primary pane is canonical for status. Most code-intel features (lint, format, autocomplete) are wired to the primary editor.

Non-ASCII filename or content shows mojibake (é instead of é)

UTF-8 encoding mismatch on read or write. AidaIDE specifies UTF-8 explicitly in most paths; if you hit this in a specific tab, capture the file and file a bug — these are tracked and patched as found.

"Recent Files" / "Recent Connections" do not survive a restart

Either the JSON file under ~/.aidaide/ is unwritable, or a save was interrupted. Delete ~/.aidaide/recent_files.json (or the corresponding connections file) and start fresh. The vault and your saved hosts in Connection Manager are not affected.

LCOT panel

LCOT panel is missing

1. You are on a feature tab. LCOT only shows on connection tabs — see Ch. 4 §Where it lives.
2. View → Toggle LCOT Panel — turn it back on.
3. The splitter has been dragged to the right edge. Drag it back left.

I clicked a WRITE command and nothing happened

Look at the terminal pane — output went there. A WRITE command may print nothing on success (e.g. systemctl restart nginx). See Ch. 4 §"I clicked a WRITE command and nothing seems to have happened".

A command fails with "command not found"

The tool is not installed on the remote device. LCOT runs commands in the remote shell; install the missing tool there (apt install nmap, etc.). See Ch. 4 §"A command is failing".

My custom command disappeared

Custom commands live in ~/.aidaide/lcot_user_commands.json. If it was deleted or corrupted, AidaIDE silently re-creates an empty one. If you have an older copy, drop it back in and reopen the panel.

The WRITE confirmation popup is annoying

It is not configurable per command — by design. It exists because clicking next to "Status" and hitting "Reboot" by accident is exactly the failure mode it prevents.

Fleet Manager and OTA

A device shows as "Offline" but I can SSH to it

The Fleet status thread probes on its own schedule. Force a refresh: right-click the device → Refresh Status. If it still shows offline:

1. Confirm the saved port matches the device's actual SSH port.
2. Check ~/.aidaide/logs/aidaide.log for fleet.status lines around the timestamp.
3. The Fleet status check defaults to port 22 in some legacy paths. Workaround: re-save the device in Fleet Manager from scratch.

See Ch. 5 — Fleet Management.

Deploy Lite says "Success" but the binary did not land

Older bug had Deploy Lite fall through to fabricated success messages when no real callback was wired (CLAUDE.md rule #4 violation, tracked). Confirm by checking the device's filesystem manually. If the bug is reproducible, capture the log — that is one of the recurring traps we want to know about.

OTA Update Manager says "No updates available" but I know there is one

1. Refresh in the OTA Update Manager. The endpoint cache TTL is a few minutes.
2. Check that the manifest URL in Settings → Network → OTA points at updates.aidaide.app.
3. R2 returns HTTP 403 instead of 404 for a missing manifest — if you see a 403 in the log, the bucket name is wrong, not your auth.

"Web Dashboard" link from Fleet menu doesn't open anything

Fall back to running it manually: python web_server.py from the AidaIDE repo root. Then browse to http://localhost:5001/fleet. Known limitation; an auto-launch fix is on the roadmap.

Discover Devices uses root as the username

Legacy default. Cancel the discovery, edit the username, retry. The default has been corrected in newer builds.

Network tools

Port Scanner / Host Discovery returns hosts I have never seen

If results look fabricated (consistent vendor strings like 2.4.1, 3.0.0, 7.4.1, 8.0.26 across unrelated hosts), the tab fell through to demo data. This is a known recurring trap (CLAUDE.md rule #4). File a bug and label demo output explicitly.

Packet Capture shows no traffic

1. Are you running AidaIDE as a user with permission to capture? On Linux you usually need sudo setcap cap_net_raw,cap_net_admin=eip $(which python3) on the interpreter.
2. Pick the right interface in the dropdown (the default may be a loopback).
3. Some BPF filters block everything if mistyped — clear the filter and verify packets flow.

See Ch. 6 — Network Tools.

Network Topology shows "Refreshed" but nothing changed

The Refresh button on the Topology tab only re-reads bookmarks in some builds; it does not re-discover the LAN. To do a real refresh, run a fresh Host Discovery sweep.

"Cisco IOS" / "Cisco Network Analyzer" — which tab is correct?

The menu label, the tab title, and the underlying class name disagree in some places. They all refer to the same feature; trust the menu path you came in from.

An exported HTML report contains my private data verbatim

For private deployments only. If you see un-escaped user-supplied strings in the report (e.g. a packet payload rendered as raw HTML), do not share that file — it is an XSS vector and the underlying bug is being tracked. Stick to JSON exports until the next patch.

Security tools

PEM contents under "View Certificate" look fake

You are seeing a known fabrication bug — the PEM tab generated a SHA-512 placeholder. Real cert inspection should use openssl x509 -in cert.pem -text -noout until the next patch lands. See Ch. 7 — Security Tools.

Cert/Vuln scans return zero findings

1. Confirm the scope (a folder, a host, the whole project). The scan honours what is selected.
2. Several Security tabs ship with simulated data unless real scanners are configured. The tab heading shows "Simulation" when this is the case. To run against real CVE feeds, configure a feed under Threat Intel Feeds first.
3. Some tabs have right-click context menus that pop on empty rows — that is a UX bug, not a missing tool.

An exported security report has raw <script> in a field

HTML escape on user-supplied values is enforced in newer builds. If you see it, do not share the report and file a bug with the input that triggered it (CLAUDE.md rule #3 — recurring trap).

Some tabs have right-click menus, others don't

Inconsistency across Security tabs. PKI Manager, IOC Database, Certificate Inventory have menus that pop on empty area (cosmetic bug). IP Access Control has no right-click at all (missing). Workaround: use the tab toolbar buttons instead.

AI Assistant and Hierarchy Builder

AI sidebar / chat takes forever to respond

1. Check the network indicator in the sidebar — slow first-byte usually means provider latency.
2. Claude Agent Manager → Test Connection — verifies the key and reachability.
3. Try a smaller model: Haiku is the speed-tier; switch in the Agent Manager.
4. Uncheck Include workspace context if your project is large.

See Ch. 8 §"AI Sidebar takes forever to respond".

"Invalid API key"

1. Re-paste the key — trailing whitespace from copy/paste is the most common cause.
2. Try Test Connection; the error message is more specific.
3. Confirm the key is for the right provider (Anthropic keys do not work with OpenAI's endpoint).
4. If you store via env var (ANTHROPIC_API_KEY), the vault overrides it — clear the vault field or set Provider → "Use environment variable".

Inline suggestions appear in unrelated files

Disable on file types where it does not help: Settings → AI → Inline Suggestions → Disabled file types → add *.html, *.md, etc. See Ch. 8 §"Inline suggestions are wrong".

Hierarchy Builder canvas is blank after I open a SoC

1. View → Reset Zoom — you may have zoomed past the canvas bounds.
2. Drill back out with the breadcrumb at the top of the canvas — you may have drilled into an empty IC.
3. Check the autosave: ~/.aidaide/builder_drafts/. If the draft file is empty, the canvas truly is empty (start placing chips from the library).

"Run" in Hierarchy Builder does not produce output

1. Confirm the SoC has a wired path from SoC In → some module → SoC Out. Loose modules with no input or output are silently skipped by the runtime.
2. Open the Trace panel (toolbar) — every signal that fires is logged there. Empty trace = nothing fired = wiring problem.
3. Make sure every Agent module has a model selected in its Properties panel; un-set models fail silently in some builds.

See Ch. 9 — Hierarchy Builder.

Live Coding Agents burns through tokens

It is supposed to — that is the "watching over your shoulder" model. Use it for focused 1–2 hour sessions, not all day. To slow it down:

• AI → Live Coding Agents → Settings → Suggestion frequency → lower it.
• Pin instructions ("only act on auth.py") to narrow scope.
• Close the tab when you walk away.

Ghost text appears in the wrong place

There is a known off-by-one on the first click of Toggle Ghost Text. Click it twice to settle.

Cameras

Camera grid is laggy or drops frames

1. Confirm network path — wifi cameras at the edge of range will drop frames regardless.
2. Settings → Network → Cameras → Default Substream = low.
3. Reduce framerate per camera (10 fps is fine for monitoring).
4. Close the grid tab when you are not actively watching — decoder threads suspend.

See Ch. 10 §"The camera grid is laggy or stuttering".

RTSP feed will not connect

1. Test the URL in VLC first (Media → Open Network Stream). If VLC fails too, it is the camera.
2. Try alternate sub-paths: stream1, stream2, Streaming/Channels/101, cam/realmonitor.
3. Embed credentials in the URL or use Camera Manager's username/password fields.

Scan for Cameras finds nothing on a LAN with known cameras

Some cameras require authentication before they respond to WS-Discovery. Add the camera manually in Camera Manager with credentials, then re-scan — it should now be picked up.

Databases

"Connection refused" to MySQL/Postgres

1. Confirm the server is actually listening (netstat -tnlp | grep 3306 for MySQL, 5432 for Postgres).
2. Check the bind address — many distros default to 127.0.0.1. Edit bind-address in my.cnf or listen_addresses in postgresql.conf to allow LAN connections.
3. Firewall: open the relevant port.

See Ch. 11 — Databases.

"Query is taking forever"

1. Cancel with the Stop button (returns to the editor).
2. Check EXPLAIN on the query — missing index is the usual cause.
3. The Query Editor has a per-query timeout under Settings → Database → Query timeout. Raise it temporarily for slow analytical queries.

WRITE confirmations are blocking my workflow

INSERT/UPDATE/DELETE always confirm before running. There is no global "trust me, do not ask" because the prior failure mode (deleted production by accident) was worse than the friction. Tick Remember for this connection to skip the prompt for the rest of the session.

Settings, themes, layout

Theme change does not apply

1. Some panels render with cached colours until they redraw. Switch tabs and back, or View → Reload UI.
2. If a plugin shipped a hard-coded colour, only the plugin author can fix it. File a plugin bug.

Settings → Accessibility (Font Scale / High Contrast / Focus Indicators) does nothing

Known issue: these toggles wire through the main window but the editor tabs do not always pick them up. Workaround: change the font scale in Settings → Editor → Font size directly.

See Ch. 13 — Settings, Themes.

Layout did not restore after restart

Workspaces auto-save on File → Exit only — if AidaIDE crashed or you killed the process, the layout from before the previous successful exit is restored.

To survive crashes, File → Save Workspace As… explicitly before risky operations. See Ch. 16 §Auto-save of the workspace.

"I lost a feature tab when I restarted"

Feature tabs (Fleet Manager, Security Scanner, etc.) are not always restored — connection tabs always are. Re-open from the menu. Tracked as a known caveat (see Ch. 16).

Command Palette does not find what I expect

1. Try shorter or different words — the matcher is fuzzy but biased toward initials.
2. Some commands are declared in the shortcut registry but not bound (legacy mass-declare cleanup pending). Use the Feature Browser (toolbar magnifier) as a fallback.

Updates and licensing

License will not activate

1. Verify network: license verification needs outbound HTTPS to AidaIDE's licensing endpoint. If you are behind a strict proxy, set Settings → Network → HTTP proxy.
2. Confirm the key matches the plan you bought (legacy base keys do not unlock the Hierarchy Builder; Pro keys do).
3. Check the renewal date in the customer portal (linked from License Status).

See Ch. 17 §"My license stopped working".

"You have exceeded your device cap"

1. Help → License Status → Devices — review currently bound machines.
2. Right-click → Revoke the one you no longer use. Takes effect within a few minutes.
3. If you cannot revoke (the old machine is gone), email support with your key — they can free a slot manually.

Update check returns 403

R2 returns 403 instead of 404 for missing buckets. Wait an hour and retry — the manifest is occasionally republished mid-day. If 403 persists past 24 hours, file a bug.

I bought a license but AidaIDE still says unlicensed

1. Help → Enter License Key — paste it again.
2. Some email clients break long keys at the wrap point. Open the email in plaintext mode or copy directly from the customer portal.

Performance

AidaIDE is using a lot of memory

The biggest contributors, ranked:

1. Camera grids — one decoder thread per visible feed. Close the tab when not watching.
2. Packet Capture with a large in-memory buffer. Lower the buffer under Settings → Network → Capture buffer.
3. Live Coding Agents keeps a long context. Close the tab to release it.
4. A connection tab with megabytes of terminal scrollback. Right-click the terminal → Clear scrollback.
5. Plugins. Disable them one at a time to identify a leaker.

The Performance Monitor at Settings → Performance → Open Performance Monitor shows per-subsystem RSS in real time. See Ch. 13 §Performance Monitor.

AidaIDE is using a lot of CPU when idle

1. Inline AI suggestions — disable if you are not actively coding.
2. A scan/probe tab left running — check the Network and Fleet menus for active background tasks.
3. Live Coding Agents in idle.

The UI freezes for a few seconds at a time

Most often a slow off-thread Tk read or a synchronous SFTP probe. The Debug Console (Ctrl+Shift+D) shows blocked-main-thread warnings — capture them and file a bug.

Diagnostics you can run yourself

These help us help you faster — please include their output when filing a bug.

Capture the latest logs

~/.aidaide/logs/aidaide.log       — main app log
~/.aidaide/logs/ssh.log           — per-connection SSH transcripts
~/.aidaide/audit.log              — vault unlock, license events, PKI

On Windows substitute %USERPROFILE%\.aidaide\logs\.

Run the bug-report bundler

Help → Report a Bug auto-collects the last hour of logs, your config (with secrets redacted), and your AidaIDE version. See Ch. 17 §Filing a bug. This is the preferred path.

Run AidaIDE in verbose mode

aidaide --log-level=DEBUG on Linux/macOS, equivalent shortcut on Windows. Re-creates the symptom and writes a much fuller log.

Run in safe mode

aidaide --safe-mode disables plugins and uses default settings. If a bug disappears in safe mode, the cause is a plugin or a custom theme.

Show the Debug Console

Ctrl+Shift+D. Real-time event stream. Useful for "this just happened, what did the IDE think happened?"

Probe a connection from outside AidaIDE

ssh -vv -p <port> user@host           # full SSH handshake trace
nc -zv host port                      # tcp reachability
ping host                             # network reachability

If any of these fail, the problem is not AidaIDE.

Verify the vault

The vault file is vault.enc under %APPDATA%\AidaIDE\ (Windows) or ~/.aidaide/ (Linux/macOS). If it has gone to zero bytes, restore from your backup — without a backup, the only recovery is Forgot password? Reset vault on the login screen.

Back up the vault file periodically. Copying it to another machine + restoring is fully supported (your master password is portable).

Filing a useful bug report

Run Help → Report a Bug. The dialog already collects most of what we need; please add:

1. What you were trying to do. One sentence is fine.
2. Exactly what you clicked / typed. "Opened Fleet → Discover Devices → Start" is enough.
3. What you expected vs. what happened.
4. Whether it is reproducible. Always, sometimes, once?
5. Your environment. AidaIDE version (Help → About), OS, network constraints (corporate proxy?).
6. Logs. Attached automatically. If the symptom is older than an hour, grab the rotated logs from ~/.aidaide/logs/ manually.
7. A screenshot if the bug is visual. Drag-and-drop into the dialog.

Submitting returns a ticket ID. Track in Help → Bug Reports. If your machine is offline, the report saves under ~/.aidaide/bug_reports/ and uploads on the next successful launch.

What you do not need to include

• Your master password. Ever.
• Your raw vault file. The bundler redacts vault contents automatically when you tick Include redacted vault contents.
• Source code from your project unless directly relevant. Reference the file path instead.

Terms & Setup

Safe mode

aidaide --safe-mode launches with no plugins, default theme, and default settings. Used to isolate whether a bug is in core or in third-party code.

Verbose / debug log mode

aidaide --log-level=DEBUG writes far more detail to ~/.aidaide/logs/aidaide.log. Use for one reproduction, then revert (the log gets large).

"Demo mode" vs real data

Several scanner-style tabs (Host Discovery, Service Detection, Threat Intel) ship with simulated data when no real backend is configured. Newer builds label this in the tab header; older builds may not. If a result list looks too clean to be true (consistent vendor versions, evenly distributed times), it probably is demo data.

Bug report bundle

The .tar.gz produced by Help → Report a Bug. Contains your last hour of logs, your config (redacted), your AidaIDE version, and any screenshots you attached. Uploaded to AidaIDE's bug-collection endpoint. Tracked under your account if you have a license.

~/.aidaide/

The AidaIDE user-data directory. On Windows it is %APPDATA%\AidaIDE\. Contains the vault, workspaces, Hierarchy Builder drafts, LCOT user commands, logs, bug reports. Not touched by the uninstaller. Back up before reinstalling if you want to preserve state.

Recurring trap

Engineering shorthand for a class of bug that has shipped more than once. Common ones called out in this guide: hardcoded port 22, fabricated demo data presented as real, UTF-8 mismatch on read/write, HTML-escape miss on exports, silent SFTP-to-local fallback on save. If you suspect a recurring trap, say so in the bug report — we will check the relevant tracker.

Composer (web vs desktop) parity

The Web Hierarchy Composer is a strict subset of the desktop builder at the moment. If a feature works in the desktop builder but the web composer is missing it, the most likely candidate is one of these (as of 2026-05-29):

• Animated signal trace — desktop only. The web composer can Validate and Run a hierarchy but does not animate the flow on the canvas.
• Right-click context menu — the web canvas supports a subset of the desktop right-click options.
• Macy tour overlay — the 16-section interactive walkthrough is desktop-only.
• Per-IC keyboard shortcuts — global canvas shortcuts work; some per-IC shortcuts are still desktop-only.

Work in progress in scheduled task ai-hierarchy-builder-gui-parity. If you find a parity gap not listed here, file a bug from the Help menu (Ch. 17 §Bug reports).

Cloud Portal — tunnel down

If a device shows offline at https://aidaide.app/web/devices when AidaIDE is running:

1. Settings → Cloud Portal on the device. Is the Tunnel up badge green?
2. If red, click Reconnect. Watch the status line for an error.
3. Most common cause: outbound TCP 443 is blocked by a firewall to aidaide.app. Allow the host.
4. Stale cert: Settings → Cloud Portal → Rotate device certificate, then Reconnect.
5. Check Help → Open log directory for cloud_portal.log — connection failures get a single line with the underlying socket error.

Cloud Portal — RD PIN issues

The 6-digit Remote Desktop PIN is shown on the host's desktop the first time a browser opens Remote Desktop. If it never appears:

• Confirm the host is currently logged in (the PIN dialog is a Tk popup; it needs an active session).
• Confirm the requesting user has at least Collaborator permission on the device.
• The PIN expires after 60 seconds — retry from the browser to trigger a new one.
• If you have lost network at the host, the PIN dialog will not refresh; restart the Settings → Cloud Portal toggle once connectivity returns.

Guest pass claim fails

When clicking a Guest Pass URL takes you to an error page:

• Not found — the URL is mistyped or the pass was issued against a different account.
• Expired — the duration has elapsed. Ask the owner to issue a new one.
• Revoked — the owner revoked it manually. Ask for a new one.
• Already claimed — guest passes are single-use. Ask for a new one.

Touch / mobile RD glitches

If the Remote Desktop tab behaves weirdly on a phone or tablet:

• No mode-switch pill — the page may have failed to load touch_modes.js. Hard-refresh (Ctrl+Shift+R on desktop; pull-to-refresh on mobile). On corporate networks check whether web/static/js/touch_modes.js is being blocked.
• Stray right-clicks while scrolling — long-press timer fires when a slow drag stalls for 500ms. Switch to Scroll mode while scrolling long content.
• The mobile shortcut bar will not dismiss — three-finger tap toggles it; if your phone has a gesture conflict, swipe up from the bottom of the bar instead.
• The wrong characters appear when typing on QWERTZ/AZERTY — confirm the layout chooser in the RD toolbar matches the host's keyboard config, not your physical keys. See Ch. 22 §International keyboard layouts.
• Pinch zoom does not affect the host — by design. Pinch is client-side only; the host has no idea you pinched.