Troubleshooting
Most Golden Terminal problems are easier to solve when you identify the failing layer before retrying commands. Start with connection state, then permissions, then the command environment, then the remote service. A failed transport and a failed command are different problems.
Quick answer: what should I check first?
Do not start by reinstalling everything. Identify whether the failure is in authorization, the local agent, the target, operating-system permissions, the command environment or a remote service.
Diagnostic order
| Symptom | First check | Do not assume |
|---|---|---|
| Customer target unavailable | Agent and network state | That the Golden server can substitute for it |
| 401 / authorization error | Account and MCP authorization | That reinstalling the agent will fix auth |
| Permission denied | Executing user and resource ownership | That sudo or chmod is automatically correct |
| Command not found | PATH, shell and working directory | That the program is not installed |
| File not found | Exact path and current directory | That the file was deleted |
| Timeout / disconnect | Actual target state | That the command did nothing |
| Remote SSH/API failure | Existing profile or service auth | That local Golden permissions are the cause |
Agent unavailable
If connected-device is unavailable, treat that as a connection problem first.
- Confirm the intended computer is online.
- Confirm the Golden agent is running on that computer.
- Confirm the machine has network access.
- Confirm the AI client still has the Golden MCP connection.
- Reconnect through the current account guide if needed.
- Run a harmless discovery call before resuming writes.
Customer execution must not silently fall back to the Golden server. Offline should remain visible as offline.
Authorization problems
An authorization problem is different from an offline agent. If the account session or MCP authorization has expired, the device may be healthy while the AI client still cannot use it.
- Open the current connection guide and sign in again.
- Confirm you are using the intended Golden account.
- Reconnect the Golden MCP integration in the AI client.
- Do not paste internal tokens or old connection codes into chat as a workaround.
Permission denied
Permission errors usually mean the connected user or remote account is not allowed to access the requested resource.
See Permissions for the full boundary model.
Command not found or wrong environment
A command can work in your interactive terminal and fail through an agent because the environment is different.
- Compare
PATH. - Check the current working directory.
- Check whether the interactive shell loads profile files that the agent does not.
- Check runtime managers such as Node, Python or Ruby version tools.
- Use an absolute executable path when that is the established project convention.
Do not globally rewrite PATH or shell profiles until you know which process actually needs the change.
File or path not found
First verify the path on the actual connected device. Relative paths are especially easy to misinterpret when the working directory changes.
If the task came from an older conversation, the remembered path may be stale. Prefer the current repository and source-of-truth files over a path copied from history.
Timeouts and uncertain outcomes
A timeout means the caller stopped waiting. It does not always prove that the remote operation stopped or failed.
Never blindly replay a state-changing command after an uncertain transport failure.
- Check whether the process or deployment is still running.
- Inspect the resulting file, service, commit or remote state.
- Determine whether the original action completed, partially completed or never started.
- Only then decide whether a retry is safe.
This matters for deployments, payments, file moves, database changes and any command that is not naturally idempotent.
Wrong machine or target
The customer runtime is exposed as connected-device. If the result looks like the wrong computer, stop before changing anything.
- Check the hostname or another harmless identity signal.
- Check which Golden agent session is currently active.
- Compare the expected project path or operating system.
- Do not compensate by guessing a remote IP, username or key.
Keep human machine roles in project context or Canon so the AI knows what the current runtime is expected to represent.
Safe diagnostic prompt
This prompt gives the AI enough room to investigate without turning troubleshooting into an uncontrolled repair attempt.
When an application on your computer crashes or will not open
Golden connection errors and software crashes inside the connected computer are separate problems. If Lightroom, Photoshop or another installed application closes while editing, freezes or refuses to launch, start with the program's crash reports and the OS event history rather than reinstalling Golden.
Read the full AI-assisted software repair and crash diagnosis guide for Windows and macOS. It covers logs, driver and plug-in isolation, data safety, application repair and verification, with a real Lightroom Classic diagnostic example.
Diagnosing a slow home router or broken Wi-Fi
A connected-device or Golden authorization failure is different from a slow ISP uplink, overloaded Wi-Fi channel or wrong port-forwarding rule on the home router. When a reachable router needs troubleshooting, establish the WAN, VPN and wireless baseline before modifying its live configuration.
See the home router optimization guide with AI for traffic diagnostics, optional services, 2.4/5 GHz Wi-Fi, VPN and external port tests. Use Permissions before asking an AI assistant to change router settings.
Configuring MikroTik RouterOS through a connected AI
If the intended target is a MikroTik router, identify the RouterOS version and exact model before suggesting commands. Golden uses an authorized computer as an execution point; access to the router still requires an existing permitted SSH or HTTPS REST path. Back up privately, protect the management route and seek approval before changes.
The full MikroTik RouterOS configuration with AI guide covers WAN, firewall, port forwarding, Wi-Fi drivers, VLAN, WireGuard, Torch/FastTrack and Safe Mode. For vendor-neutral home-router troubleshooting, see Home Router Optimization.
Checking and repairing a server through Golden Terminal
A responsive Golden connection does not mean that every Linux service, Docker container or website is healthy. If an authorized local server or VPS is slow, full or failing, identify the actual connected target and request a read-only baseline before restarting anything.
Use the AI server diagnostics, monitoring and repair guide for disk blocks/inodes, CPU and memory, systemd, containers, logs, network and public HTTPS verification. Read Permissions before making changes or requesting elevated rights.
FAQ
Should I restart the computer first?
Usually not as the first diagnostic step. A restart can hide evidence and does not distinguish authorization, permissions, PATH, target selection or remote-service failures.
Should I reinstall Golden if a command fails?
Not unless the evidence points to the agent installation itself. A command failure can come from the operating system, project runtime or remote service while Golden remains healthy.
What if the AI says the operation timed out?
Inspect the actual target state before retrying. The operation may still have completed.
What if the AI asks me to paste a password to debug access?
Prefer the existing local credential, SSH profile, environment variable or credential store. See Golden Secrets / Secure Input.
Ready to continue?
Use the current connection guide, then return to Help whenever you need the next layer.