Troubleshooting

Solutions to usage problems and resolved issues for Libra command workflows and SSH remotes

Troubleshooting

This section is the running log of usage problems and their solutions. Each entry captures the symptom, the root cause, the fix, and the verification steps so the same resolution can be reused when the same problem appears on another machine, network, or repository.

Issue #1: SSH clone failed with a pkt-line protocol error and SSH exit status 255

  • Status: Resolved
  • Date: 2026-11-10
  • Area: SSH remotes

Symptom

libra clone git@github.com:gitmono-dev/megaui.git failed while discovering references from the remote:

Connecting to git@github.com:gitmono-dev/megaui.git ...
fatal: remote discovery failed: failed to discover references from 'git@github.com:gitmono-dev/megaui.git/':
Network Error: pkt-line protocol error: incomplete four-byte header; SSH exited with status 255;
check SSH connectivity, trusted host keys, ssh-agent authentication (load or unlock the key first),
and remote repository access

Hint: check that the remote serves Git data and that a proxy has not altered the response

Root cause

The SSH transport used for the Git remote terminated before the protocol exchange could finish. OpenSSH exited with status 255, so the Git pkt-line stream observed by the client ended before a complete frame header arrived. The truncated stream was then reported as a pkt-line protocol error (incomplete four-byte header) with a network hint.

The SSH key itself was valid and loaded, so the failure was at the transport layer — reaching the remote over the configured SSH route — rather than at repository authorization.

Solution

Route the SSH connection to GitHub through the SSH endpoint that runs over HTTPS port 443, which stays reachable when outbound SSH port 22 is filtered or unavailable.

Add an SSH host block to ~/.ssh/config:

Host github.com
  HostName ssh.github.com
  Port 443
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  StrictHostKeyChecking accept-new
  UserKnownHostsFile ~/.ssh/known_hosts

Then retry the clone with the same remote URL.

Verification

ssh -T git@github.com
libra clone git@github.com:gitmono-dev/megaui.git

The SSH check completes the authenticated handshake and the clone finishes fetching and checking out the working tree.

Adding a new entry

Add new usage-problem entries under this section as they are resolved, keeping the same structure: symptom, root cause, solution, and verification.