REFERENCE

Troubleshooting

Diagnose SSH, authentication, network, AI provider, device-command, and local diagnostic issues without exposing sensitive data.

Verified against AI NetShell 0.4.11

Purpose#

Use the visible error and the smallest safe diagnostic test to separate connection, authentication, device, and AI service problems. Gather support information without sharing credentials or an unredacted copy of your environment.

Before You Begin#

Record the exact error text, time, time zone, and action that produced it.
Confirm the app version under Settings > About.
Use only systems you are authorized to test.
Do not paste passwords, private keys, API keys, tokens, or full configuration files into a support message.

Steps#

1. Troubleshoot SSH connection failures#

Symptom	Checks
Connection is unreachable, refused, or times out	Confirm the saved host and port, DNS resolution, VPN connection, Windows route, firewall or ACL, and that SSH is enabled on the device. Test the same endpoint from an approved administrative path.
First-use host key is unknown	Compare the displayed fingerprint with a value obtained through a trusted channel, then accept only if it matches.
Host key mismatch	Stop. Confirm that the device was not replaced, rekeyed, or redirected. The app refuses the connection and does not offer an override.
Session connects and then drops	Check device logs, idle limits, concurrent-session limits, management-plane load, and intervening VPN or firewall timeouts.
Older device cannot negotiate SSH	Edit the device and enable Allow older SSH algorithms only after confirming that the authorized device requires it. Prefer upgrading the device's SSH configuration. The option widens compatibility for older devices, and it never turns on the none cipher or DSA keys.

Do not enable legacy compatibility as a general fix for an incorrect host, blocked port, or failed Credential.

2. Troubleshoot authentication failures#

For authentication failed:

Edit the device and confirm the assigned Credential and username.
Confirm that the device still accepts the selected password, private-key, or agent method.
If a password, passphrase, or provider key was rotated, save the new value in the Credential or provider setting.
For a private key, confirm the saved file still exists and is readable by your Windows account.
For SSH agent authentication, confirm the agent is running, the intended key is loaded, and the configured agent endpoint is available.
Check whether the server requires an interactive challenge that the selected method does not answer.

Do not send the secret to support to prove that it is correct. Test it through an approved client or replace it with a temporary least-privilege Credential.

3. Separate network timeouts from device delays#

A connection timeout means the app did not establish the network session within its bounded connection period. A command timeout happens after connection and can indicate a slow or non-returning device command.

For a connection timeout, check routing, DNS, VPN, firewall rules, the target port, and device reachability.
For a command timeout, reconnect and start with a small read. Check device CPU, management-plane load, CLI mode, and whether the command is supported on that firmware.
Do not repeatedly retry a command that may allocate resources, start a trace, or wait indefinitely. Use a platform-approved diagnostic method instead.

If a read, a change or a rollback says This session is busy (task). Try again in a moment., another AI NetShell task is using that device session, and nothing was sent. A change or a rollback keeps the session from its first line to its last cleanup line. Wait for it to finish, then try again. A change or a rollback waits up to 4 minutes for the session, and a read waits up to 1 minute.

4. Troubleshoot AI service and provider failures#

Use the app's heading and reason together. Read the account-related setup failures as:

Model availability check failed
AI NetShell could not read which AI providers are set up. Press Retry.
AI NetShell could not check whether your plan includes your own API keys. Press Retry.
AI NetShell could not complete the provider setup and plan checks. Press Retry.
This model is no longer offered. Pick another one.

An investigation can also show Investigation failed followed by the provider or connection reason.

Work through these checks:

Select Retry once after confirming the network is available.
If the failure identifies the account session and offers Open Account, use it to repair the account connection.
Open Settings > AI Providers and confirm that the selected payment route is set up.
For your own provider key, save the current key again and confirm that your plan includes Your own AI.
For ChatGPT sign-in, open Settings > AI Providers and confirm the account is still signed in. If it says Your ChatGPT sign-in expired. Sign in again., select Sign in with ChatGPT account. Then select a model from the Your ChatGPT account group.
If the selected model is no longer in its catalog group, choose an offered model.
Under Settings > Network, run Test connection. This checks the configured DNS, proxy, TLS, and HTTP path to the app's fixed test endpoint. It does not validate a provider key, account entitlement, or selected model.

If an investigation on a ChatGPT model shows Your ChatGPT sign-in expired. Sign in again to keep using ChatGPT models., select Sign in again. It opens Settings > AI Providers and starts the ChatGPT sign-in in your browser. The sign-in normally renews itself. A sign-in made before version 0.4.9 cannot renew itself, so after you update, select Disconnect in Settings > AI Providers, then select Sign in with ChatGPT account.

If the error says the named provider request did not complete and may or may not have reached the provider, the request reached an uncertain transport state. Check the account usage or credit balance before sending the same request again. The app automatically retries only an explicit rate-limit response and stops after a bounded number of attempts and waits. A rate-limit failure tells you to try later or check the provider's rate-limit status.

If Lina cannot include every open terminal, read the notice below AI watches. It states how many terminals Lina is reading out of those open in the investigation. Select Open account settings if the notice says the account must be connected. If it identifies a plan boundary, use its plan link: See plans & pricing when you have no paid plan, Change plan to open your billing portal when you already pay for one, or Plans and billing when the app cannot tell yet. If the notice begins Lina could not be told about the terminals you just opened., keep the listed terminal count as the current coverage and review the error text before trying again.

If the conversation displays Earlier updates were truncated (n events beyond the replay buffer)., let the investigation settle, then use Export > Technical notes to review the recorded case and evidence. Do not repeat commands solely because earlier live updates are missing.

If chat shows Sign in to use Lina, select Sign in with your browser and complete the account flow. You can also use Settings > Account. If browser sign-in expires, start it again rather than continuing an old approval page.

Included AI and Your own AI use different routes. A successful Included AI request does not prove that a direct provider route works, and the reverse is also true.

5. Check a run that appears stuck#

Open Discovery and inspect the progress line and Crawl activity. Each read appears in Crawl activity as it starts, shown as reading command (n of m), so the newest entry for a device names the read in progress. Use Filter by device to isolate the last device being attempted. A quiet configuration backup read can legitimately take several minutes.

When the app shows No progress for time. A slow device or a configuration backup read can take several minutes, so this may still be working; if nothing changes for much longer, kill the crawl and check the batch report., allow for the slow operation first. If the display remains unchanged much longer, open Crawl actions, select Kill crawl, and review the completion report. A killed or incomplete run is not a successful comparison baseline.

6. Troubleshoot an update#

If Restart now is unavailable, read the reason beside it and finish the named work before retrying. The app does not restart itself while work is in progress.

An open remote desktop (RDP) tab does not stop an update. Before the installer runs, AI NetShell closes its remote desktop helper, so any RDP session ends with the restart.

If automatic preparation fails, open Settings > Updates and select Open the download page. Check that the installer is signed by PACKET 365 LLC before running it by hand.

7. Handle unsupported devices and commands#

Check the live-verified platform table in Devices & connections. A platform appearing in a selector is not by itself a GA support claim.

If the platform is not in the table, do not rely on AI-generated device commands for production work.
If the app refuses a command before sending it, the action was outside the available policy or workflow. Do not rewrite it merely to evade the refusal.
If the device returns a CLI error, capture the sanitized error line and confirm the platform, firmware, privilege level, and CLI mode.
If the session signs in at privilege level 1, read the app's explanation. Either reconnect with an account that signs in at the level the read needs, or add an Enable password (optional) to the Credential so the app answers the device's second prompt. See Credentials.
If a command is valid on another firmware or management mode, use a read-only alternative verified for the actual device.
If the terminal prints This session is busy (task), so the host's sign-in steps were not run. Reconnect when the session is free., the app did not answer the device's enable prompt. Reconnect when that task has finished.
Cisco FTD is read-only in the governed GA workflow. RouterOS is not in the live-verified support table.

8. Find local logs and diagnostic records#

AI NetShell stores its local application data under the Windows app-data directory for com.ainetshell.app, inside the shellshock subfolder. On a standard installation, this is:

%APPDATA%\com.ainetshell.app\shellshock

Useful records include:

Location	What it can help diagnose	Sensitive content to expect
`audit.jsonl`	AI command attempts, approvals, outcomes, and verification records	Device names or addresses, usernames, commands, and returned details
`investigation_timelines\`	Run timing and investigation outcome records	Run identifiers, failure details, and operational context
`scope_grants.log`	Active Discovery target approvals	Network ranges, addresses, device and Credential references
`inventory.json`, `profiles.json`, `known_hosts.json`, `settings.json`	Saved endpoint, authentication-profile, host-key, and app-setting state	Addresses, usernames, local file paths, fingerprints, provider names, and environment details
`case-notes\`	Case notes saved here only when the notes folder could not be used	Device output, addresses, names, configurations, and findings

Case notes are normally saved outside this folder, in Documents\AI NetShell\case-notes or the folder set under Settings > General > Notes save location. When that folder cannot be used, the note lands in case-notes\ here, and the saved message says where it went. Case notes and other exports you create contain investigation evidence, so review them the same way.

Saved secret values are handled separately through Windows Credential Manager, but local records and device output can still contain sensitive material. Do not share the whole application-data folder.

9. Prepare a redacted support packet#

Create copies of only the relevant excerpts. Never edit the original audit record in place.

Include:

App version
Windows version
Device platform and firmware, if relevant
Connection method and port
Exact error text and sanitized status code
Time, time zone, and a short sequence of steps
A small redacted log or timeline excerpt tied to that time
Whether Test connection passed or failed, for an AI network issue

Redact as follows:

Remove or replace	Safe approach
Passwords, API keys, access tokens, refresh tokens, private-key material, passphrases, recovery codes, and configuration secrets	Delete the value completely. Use `[SECRET REMOVED]`; never preserve a prefix or suffix.
IP addresses, hostnames, network ranges, device names, organization names, and interface descriptions	Replace consistently with labels such as `DEVICE-A`, `HOST-A`, and `NET-A`.
Usernames, email addresses, account IDs, and Credential names	Replace with role labels such as `ADMIN-USER` or `CREDENTIAL-A`.
Windows paths	Remove the personal directory portion and keep only the relevant filename or final folder.
Configuration and command output	Keep only the few lines needed to show the error. Remove unrelated addresses, names, keys, hashes, community strings, and banners.

Review the redacted copy as plain text before sharing it. Search for common secret prefixes, your usernames, organization domains, IP ranges, and device names. Screenshots need the same review because terminals and dialogs can expose addresses, usernames, paths, and provider details.

Expected Result#

You can identify whether the failure is in network reachability, SSH negotiation, authentication, device behavior, provider setup, or AI connectivity, and provide a minimal redacted record if support is needed.