Terminal troubleshooting

What it is

A checklist for the problems you are most likely to hit in the Terminal. Work top to bottom: most failures are the Agent, the network path, or the credentials — in that order.

How to fix “Agent not available”

You click a device with a private IP and the CreaRack Local Bridge modal appears instead of a session. That means CreaRack could not reach a running Agent on this PC.

1. Click Activate Bridge. CreaRack first tries to wake an already-installed Agent; if none answers within a second, it downloads CreaRackAgent.exe.
2. Open the downloaded file. The Agent self-installs and the modal switches to Bridge Established!, then your pending session opens.
3. If the download did not start, click Try downloading again.

If the modal keeps coming back, check the Agent directly: open http://127.0.0.1:5050/health in a browser tab on the same PC. A healthy Agent answers {"status": "healthy"}. If it does not, start CreaRackAgent from the Start menu, or check whether another program holds port 5050 (netstat -ano | findstr :5050 in PowerShell).

Use 127.0.0.1, not localhost. The Agent listens on IPv4 only. On Windows, localhost often resolves to IPv6 (::1) first, so http://localhost:5050 can show “connection refused” while the Agent is alive. CreaRack itself always uses http://127.0.0.1:5050.

How to fix a session that will not open

The Agent is running but the terminal shows a timeout or never gets a prompt:

1. In the sidebar, run Health Check to confirm the device answers from the Agent’s network.
2. Use Port Scanner against the device IP and port 22. SSH may be disabled or on a non-standard port.
3. Check device ACLs: the IP that must be allowed is the PC running the Agent, not the CreaRack cloud.
4. If the session froze after working fine, close the tab and click the device again. Expired sessions are detected and replaced automatically.

If the terminal disconnects right after opening, your Agent may be outdated. Check the version in the Agent Fleet widget of the Observatory and re-run the installer to update (current release: v2.3.0).

How to fix credential failures

“Authentication failed” comes from the device, not from CreaRack:

• Managed devices: credentials are stored in Network Management and resolved server-side by the Agent — your browser never handles them. If they changed on the device, update them in the Rack Editor properties panel, or via Config → Stored Credentials, and reconnect.
• Detected devices: the connection form pre-fills IP and username, but you type the password every time. It is never sent to the browser. A typo here is the most common cause — passwords are case-sensitive.
• Manual sessions: everything is typed in the Manual SSH Session form. Verify against the device console.

Troubleshooting the Agent itself

• Agent online locally but red in CreaRack: the outbound WebSocket to the SaaS is blocked. Check internet access and the corporate firewall on the Agent PC.
• After laptop sleep: the Agent self-recovers within ~15 seconds of waking. Give it 30 seconds before restarting it.
• Deep diagnostics: open http://127.0.0.1:5050 and use the Debug tab for live logs (errors in red), or read %APPDATA%\CreaRackAgent\agent.log if the Agent will not start at all.
• 401 errors when calling the Agent’s API by hand: expected. Since v2.1.2 the local API requires a Bearer token that CreaRack injects into your browser session automatically. Use the CreaRack UI instead of raw API calls; if a page shows persistent auth errors, refresh it.

Related

• [[crearack—terminal—que-es-terminal]] — Terminal overview
• [[crearack—terminal—local-agent]] — install, status, and fleet
• [[crearack—terminal—sesiones-ssh]] — session management
• [[crearack—terminal—sftp]] — file transfer issues
• [[crearack—terminal—todos-los-dispositivos]] — the device sidebar and its filters

Véase también

• [[crearack—terminal—que-es-terminal]]
• [[crearack—terminal—local-agent]]
• [[crearack—terminal—sesiones-ssh]]
• [[crearack—terminal—sftp]]
• [[crearack—terminal—todos-los-dispositivos]]