Skip to article

Troubleshooting

Applies to the current released clients and Bridge. Check versions before applying guidance for a different platform or older release.

Start with a small check

forge --version
forge whoami --format json
forge doctor --format json

Inspect errors, failed checks and next_actions. A doctor success checks workstation/login readiness, not a repair outcome on a remote machine. For one target, use forge devices show --device <device-id>.

These responses can identify your workspace or devices. Review them before sharing; do not paste complete outputs into public discussions.

Installation and login

The login/installation steps below describe a personal technician client. Whisper is currently disabled: a missing navigation action or disabled saved-link notice is expected, not a reason to reinstall the CLI, rotate credentials or retry a personal login in shared chat. Its workspace configuration is retained; use your own local agent/client for ordinary access.

Symptom Next step
forge not found, or the old version still runs Restart the terminal and coding agent after installation. On Windows, Get-Command forge shows the selected command; on Linux, command -v forge does the same. Check the launcher path from the platform install guide.
Missing bundled artifacts Repair with the complete signed package. Do not copy an isolated executable from another version.
Invalid hash, signature or unexpected publisher Stop. Obtain the expected verified release through the trusted download/software channel; never disable verification.
No workspace, wrong workspace or missing device Confirm whoami, use forge tenant list, then select the intended profile or sign in with an explicit workspace. Names and email addresses are not membership proof.
Login expired Run forge login for the affected profile and complete browser authorization.
Linux credential provider not ready Run forge credentials status in the actual user/agent session. Restore the configured keyring/key access; do not silently switch provider or relax permissions.
A signed-in browser tab no longer has access Reload, verify the selected workspace and current membership. An old page or bookmark does not preserve authorization.

Installation details: Windows ยท Linux.

Device connection

  • Offline device: check the last-seen time, power and network with the customer. Offline is not proof of revocation or a failed update.

  • Device busy: coordinate with the technician holding control. One identity may use multiple channels; another identity cannot take over silently.

  • Stale local connection: use the supported disconnect, then reconnect:

    forge device disconnect --device <device-id>
forge device connect --device <device-id>

    This preserves profiles and persistent host-key pins.

  • Host-key mismatch: stop and investigate the device's identity or reinstall/transfer history through a trusted channel. Do not delete pins or disable SSH checks to force a connection.

  • Relay or Bridge interrupted: channel loss stops access. Check the remote outcome before repeating a command or transfer; there is no automatic replay guarantee.

  • Remote path or command fails: use the target OS's paths and shell. Windows commands run as LocalSystem through PowerShell; Linux commands run as root through /bin/sh, not in the customer's desktop session.

No inbound firewall rule, Windows OpenSSH server or VPN installation is needed on the target. forge device relay probe is migration-specific, not a general connectivity repair command.

Enrollment and Rescue

An enrollment link may be expired, consumed, revoked or tied to a release that is no longer available. Inspect the share/enrollment status before issuing another package. A downloaded package does not prove installation; a consumed code does not prove authenticated online health.

Preserve the generated Windows filename and the whole Linux package with its signed sidecars. Keep bootstrap/code files private.

Current Windows enrollment can provide a copyable diagnostic report. Review its contents before sharing through a private support channel. Installed version, selected worker version, presence and fresh health are different observations; one reported version alone does not prove update success.

For Rescue, run forge rescue doctor and use the creating profile. capsule_issuer_not_ready requires the approved matching Rescue configuration, not a newly generated arbitrary key or an unsigned bypass. See Rescue prerequisites.

Treat unconfirmed Rescue cleanup as unconfirmed. Keep recovery information and follow the returned next actions; local disconnect is not proof of remote process removal.

Diagnostics and customer records

  • Partial snapshot: retain successful sections and inspect warnings. Choose only implemented sections for the target platform.
  • cleanup_required: the snapshot may be available locally, but remote cleanup failed or is unknown. Remove only the operation's reported temporary directory through authorized access.
  • Directory/case version conflict: read the latest record and reconcile edits. Case, note, draft and device-link versions are independent.
  • Write timed out: completion is unknown. Inspect current records before retrying. Retry note creation with the same key and unchanged payload; other creates can duplicate records.
  • Draft export unavailable: review the exact current revision on the website. Any content or recipient edit clears earlier review.
  • Evidence unavailable: current authorization or retention may have changed. A case link never overrides those boundaries.

Service errors and support

The public guides are served separately from the Bridge application. During Bridge maintenance you can still consult them, but reading a guide does not restore login, device access or interrupted work. If an old documentation tab shows outdated guidance, return to the stable documentation home rather than refreshing a generation-specific snapshot link.

If the website shows maintenance or a service error, wait for it to recover and refresh. Confirm the state of interrupted work before retrying a mutation. An error notification is not proof that a task failed, completed or recovered. An operator may supply an approximate maintenance window. It is an estimate, not a promised completion time; an expired or unavailable estimate does not mean the service has recovered.

For a private support request, provide the approximate time with time zone, platform, CLI version, the operation name and bounded error code. Explain expected versus observed behavior. Include a narrowly scoped diagnostic snapshot only when requested and authorized.

Do not include passwords, tokens, private keys, enrollment links, generated secret-bearing filenames, raw command transcripts or unnecessary customer data. Report suspected vulnerabilities privately to Ready IT ApS rather than posting a reproduction against a real device.