# Troubleshooting

The problems people hit most with sign-in, git, the CLI, CI, caissons, sandboxes and moving repositories, and the fix for each.

## Start with doctor

```sh
sailfork doctor
```

`doctor` checks sign-in, the token's expiry and scopes, git and its credential helper, whether the SSH port is reachable, the server and its version, and the clone you are in. Each problem prints the command that fixes it, on a line that starts with `fix:`. It exits 1 when a check fails.

```text
ok    auth.signed_in         signed in to https://sailfork.com as fenil (token from keychain)
fail  git.credential_helper  git's credential helper sailfork for https://git.sailfork.com does not exist, so git push and fetch fail
                             fix: sailfork auth setup-git
```

The checks are `auth.signed_in`, `auth.token`, `git.credential_helper`, `ssh.reachable`, `host.reachable`, `server.version`, `repo.resolution` and `cli.update`. For a script, print only the failures:

```sh
sailfork doctor --json --jq '.checks[] | select(.status != "ok") | "\(.id): \(.fix // .summary)"'
```

## Sign-in

### `That email and password do not match an account.`

The email or the password is wrong. Check the address you signed up with. Any verified address on the account works. If you signed up with GitHub, you have no Sailfork password: use Sign in with GitHub.

### I forgot my password

On the sign-in page, choose Forgot your password? and enter your email. The link works once, for one hour, and changing the password signs you out everywhere else.

### My reset link says it expired

Links last one hour, and only the newest one works. Ask for a new link and open the latest email. You can ask again after a minute.

### I lost my authenticator

Sign in with one of the ten recovery codes you saved when you turned on the second step, then set up the authenticator again. Each code works once. If you have no codes, write to us through [the contact page](https://sailfork.com/contact).

### `the sign-in expired; enter your password again`

You have 5 minutes and 5 attempts to answer the second step after a correct password. Start again from the password.

### Too many attempts

Sailfork answers 429 past 20 sign-in attempts a minute from one address, or 10 for one account. Wait for the `Retry-After` seconds. See [Rate limits](https://sailfork.com/docs/rate-limits).

### `this account is suspended; write to us through the contact page`

The account is suspended. Use [the contact page](https://sailfork.com/contact).

### `verify your email address first: open the link we sent you, or send a new one from Settings, Account`

CI runs and sandboxes need a verified email address. Open the verification link from your inbox, or go to Settings, Account, find the address under Email addresses and choose Resend link. The link works for 24 hours. See [Your account](https://sailfork.com/docs/account#email-addresses).

### I want to delete my account

Settings, Account, Delete account. It takes effect after 14 days, and signing in before then cancels it. If you are the only owner of an organization, you get `you are the only owner of <org>: make someone else an owner or delete the organization first`.

## Git push and SSH

[Git access](https://sailfork.com/docs/git-access#common-errors) has the full table of push errors. These are the ones people ask about most.

### Git asks for a password

Over HTTPS, the username is your handle and the password is an access token. Paste a token, or run this once and git stops asking:

```sh
sailfork auth setup-git
```

A token whose owner has a different handle than the username is refused. See [Access tokens](https://sailfork.com/docs/tokens).

### `insufficient_scope: this token needs repo:write`

The token can read but not push. Create one with `repo:write`, or run `sailfork auth login` for a token with every scope. See [Access tokens](https://sailfork.com/docs/tokens#scopes).

### `repository not found`

The name is wrong, or the repository is private and your account cannot see it. A private repository you cannot read looks the same as one that does not exist. Check the owner and spelling. If the repository belongs to an organization, check that you are a member and that a token limited to certain repositories includes it.

### `you do not have permission to push to this repository`

You can read the repository but not write to it. Ask an owner for Write access. On a public repository you can push a branch named `contrib/<your handle>/<name>` and open a pull request from it. See [Roles and permissions](https://sailfork.com/docs/permissions).

### `protected branch: changes to main must go through a pull request`

A branch rule requires a pull request. Push another branch and open one. Repository admins can push directly. See [Branches and protection](https://sailfork.com/docs/branches).

### `the pack is over the <n>-byte push limit (SAILFORK_PUSH_MAX_PACK_BYTES)`

The push is bigger than the server allows. Push a large history in parts: one branch or an older slice first, then the rest. A single object over the limit stops with `an object in the pack is <n> bytes, over the <n>-byte object limit`. See [Limits](https://sailfork.com/docs/limits#repositories-and-pushes).

### `acme requires two-factor authentication: add a passkey or an authenticator app in Settings, Security to get back in`

The organization requires every member to have a passkey or an authenticator. Add one under Settings, Sign-in and sessions. Access returns at once.

### Free-plan refusals

`This account stores <size> and the Free plan includes <size>. Pushes and commits that add data are refused until you free space...` means a Free account is over its storage allowance. Delete repositories, or move to a paid plan. Reading, cloning and deleting still work. See [Plans, billing and usage](https://sailfork.com/docs/billing).

### SSH: `Permission denied (publickey)`

Git is not offering a key Sailfork knows. Check these:

- The key is added under Settings, Keys and tokens, with Used for set to Push and pull. A key added for Signing commits does not authenticate.
- Sailfork accepts ed25519, ECDSA, and RSA of 2048 bits or more. It refuses DSA. If yours is older or smaller, make a new one with `ssh-keygen -t ed25519`.
- `ssh-keygen -lf ~/.ssh/id_ed25519.pub` prints the fingerprint to match against the one shown under the key.

Adding a key can fail with `unsupported key type <kind>`, `key is not a valid OpenSSH public key`, or `RSA keys must be at least 2048 bits, this one is <bits>; make a new one with ssh-keygen -t ed25519`.

### SSH: `Hi fenil! You've successfully authenticated, but sailfork does not provide shell access.`

That is the success message from `ssh -T git@git.sailfork.com -p 2222`. Sailfork gives no shell. Use `git clone` and `git push`.

### SSH is unreachable

Some networks block port 2222. `sailfork doctor` reports `SSH git.sailfork.com:2222 is unreachable from this network` and says to use HTTPS. `sailfork repo clone` uses HTTPS by default, and falls back to it when you ask for SSH and the port is closed.

### My commits show as unverified

Add a key with Used for set to Signing commits, then set `gpg.format ssh`, `user.signingkey` and `commit.gpgsign`. The Keys and tokens page prints the commands.

## The CLI

### `not signed in to <host>; run sailfork auth login --host <host>`

The CLI has no token for that host. Run the command it prints. On a machine with no browser, run `sailfork auth login --device` and approve the code on another device, or set `SAILFORK_TOKEN`.

### `your token was revoked or has expired (run sailfork auth login)`

The token the CLI is using no longer works. A token from `auth login` lasts 90 days. Sign in again. `sailfork doctor` shows how many days a token has left.

### `this token does not have the <scope> scope`

The token lacks a scope the command needs. After a CLI login, run `sailfork auth login` again for a token with every scope. For a token you made by hand, create one that includes the scope: `sailfork token create <name> --scopes <scope>`.

### Exit codes

Every command exits with a code a script can read. 3 is not signed in or token rejected, 4 not found (for a private repository also means you cannot see it), 5 forbidden, 6 conflict, 7 network failure, 8 validation, 9 unavailable (HTTP 429, 502, 503, 504), 10 precondition failed, 11 a person must approve a held write, 12 pending. See [Install the CLI](https://sailfork.com/docs/install#exit-codes).

### A network error or a timeout

The message ends with a hint. `raise SAILFORK_TIMEOUT (seconds) for slow calls, or retry` means a request timed out: the default is 120 seconds. `check the host (--host, SAILFORK_HOST or SAILFORK_URL) and the network` means the server did not answer. `sailfork doctor` reports `cannot reach <host>` with a `curl` command to try.

### `server older than the CLI`

The CLI is newer than the server. Newer commands may not exist there yet. Run `sailfork doctor` to compare versions. If the CLI is the older one, run `sailfork upgrade`.

### Which repository?

A command needs a repository and cannot find one. Run it inside a clone whose remote is on a Sailfork host, or pass `-R owner/repo`, or set `SAILFORK_REPO=owner/repo`. `sailfork doctor` prints which repository it resolved and where from.

### The token is in `hosts.toml`, not the keychain

When the keychain is not available, or `SAILFORK_NO_KEYRING` is set, login stores the token in `hosts.toml` in the config directory with mode 0600. It prints `Keychain not used (<why>); the token is stored in <path> (mode 0600).`

### A command refuses to run without a terminal

A command that needs an answer fails and names the flag when it cannot prompt: for example `--yes` for a delete. `CI=true` and `SAILFORK_NO_PROMPT` turn prompts off on purpose.

### Output is cut off

A coding agent gets stdout capped at 65,536 bytes, cut at a line, with a note saying how to get the rest. Pass `--max-bytes 0` to lift the cap.

## CI

### A new repository says there is nothing to run

Runs read the workflows on the default branch, and a repository nobody has pushed to has no default branch yet. Push your code together with a workflow, and the first run starts on its own. See [CI](https://sailfork.com/docs/ci).

### No runs start

Workflows run on your organization's own compute: a connected Depot account, or an online Drydock host. An organization with neither gets no runs, and a repository without an organization gets none either. Starting a run by hand says `this repository has no CI compute: connect a Depot account or a Drydock host to its owner`. An owner connects a provider in the organization's Settings, CI, or registers a Drydock host. See [Sandboxes](https://sailfork.com/docs/sandboxes).

### A workflow is listed as Won't run or Needs setup

The Runs page checks the workflows on the default branch. Won't run lists what never starts or fails at once. Needs setup lists what reads empty until you set a secret or variable here. May fail lists steps detected by name that might still work. Fix the first group, set what the second names, and push again.

### A run failed with `Invalid workflow file <path>: <reason>`

The workflow's YAML did not parse. Fix the file the message names and push.

### A run is stuck at `Waiting for a Drydock host with room (number 3 in the queue)`

Every host of the organization is busy. The run starts when one has room. Check hosts with `sailfork sandbox host list --org acme`.

### A job stops with `The Drydock host running this job disconnected`

The machine lost its connection or restarted. Sailfork claims the job again, up to 3 times. Check the host with `journalctl -u drydockd -f` on the machine.

## Caissons and sandboxes

### A write is HELD FOR A PERSON

A path under an Ask me rule holds the write instead of applying it. The caisson waits under Needs you on the caissons page, and the change lands only when a person with write access allows it in the browser. No access token can allow it, so the agent cannot allow its own write. The CLI exits with 11. While one write is held, a second is refused, and writes to other paths keep working. The agent withdraws a held write by restoring that path alone, with `sailfork caisson restore`. Owners set the rules in Settings, Caissons.

### A write is refused with 403

A Never rule refuses the write outright, and so does a path outside the caisson's scope. Do not retry. Write elsewhere, or change the scope or the rule.

### Opening another caisson is refused

A repository has a limit on live caissons, 8 by default. Merge or close one. Owners set the limit in Settings, Caissons, under Live caissons per repository. A caisson with no writes for 120 minutes closes itself by default, and its branch is kept.

### How do I run my tests on a caisson's edits?

```sh
sailfork caisson test c-ab12cd --org acme -- cargo test
```

It puts the caisson's code, the branch plus uncommitted edits, in a throwaway sandbox, runs the command and removes the sandbox. The command exits with its own code, and 124 if `--timeout` killed it, so a failing test is a normal answer. `--keep` leaves the sandbox running for another run. Your organization needs a Drydock host first.

### A sandbox will not start because every host is busy

Creating a sandbox, and `caisson test`, wait for room: 60 seconds by default, up to 600 with `--wait`. `--wait 0` fails at once. They also wait for a host that is reconnecting after a Sailfork update. If it still fails, no host of the organization is online. Check `sailfork sandbox host list --org acme`, and the daemon with `journalctl -u drydockd -f`.

### How do I add a Drydock host?

An organization owner runs `sailfork sandbox host add build-1 --org acme`, which prints a token once. On a Linux machine with Docker and systemd, run `curl -fsSL https://sailfork.com/install/drydock | sh`, then `sudo drydockd install --server https://sailfork.com --token <token>`. Check it with `sailfork sandbox host list --org acme`: the host should show online.

### `pip` or `node` is missing in a sandbox

Without `--image`, a sandbox runs `buildpack-deps:noble-scm`, Ubuntu 24.04 with git, curl, wget and python3 but no pip, node, compilers, Go, Rust or Java, and an empty apt index. Pick an image for your stack, for example `--image python:3.12-slim`, `node:22`, `rust:1` or `golang:1.23`. To stay on the default image, run `apt-get update` before `apt-get install -y`. A command not found there exits 127, and the CLI prints a hint.

### A process in a sandbox ran out of memory

The process exits with 137 and the sandbox keeps running, so the next command works. Give heavy builds more with `sailfork sandbox create --memory 4096`. The default is 2048 MB.

## Moving repositories

### Move from GitHub

Authorize GitHub, pick repositories or whole organizations, and Sailfork copies code, issues and pull requests. Nothing changes on GitHub. See [Move from GitHub](https://sailfork.com/docs/migrate).

### Move from GitLab, Bitbucket or Azure DevOps

Paste the repositories into the migrate page and run the script it writes. It copies every branch and tag and checks nothing was left behind. See [the migrate page](https://sailfork.com/migrate#script).

### Do commit hashes change?

No. History is copied as it is, so hashes, signatures and links to commits keep working.

### Errors during a move

| Message | What to do |
| --- | --- |
| `connect your GitHub account first` | Connect GitHub under Settings, Sign-in and sessions, Connected accounts. |
| `this GitHub installation is not connected to your account` | Pick an installation your own GitHub account can reach. |
| `your GitHub account cannot read <org>/<name>` | Your GitHub account needs pull access to the repository. |
| `Sailfork cannot read <org>/<name> on GitHub` | The GitHub App cannot reach the repository. Check that the installation includes it. |
| `archiving <org>/<name> needs admin access to it on GitHub` | Choose an option other than archive for what happens to the original, or ask someone with admin access on GitHub. |
| `<name> already exists` | You already have a repository with that name here. Rename one. |
| `<org>/<name> is already being moved, or its name is taken` | A move for that repository is already running, or the name is used. |
| `the copy is not ready to switch` | Wait until the copy shows ready, then switch. |
| `this repository already lives on Sailfork; delete it from its settings` | You tried to cancel a move that already switched. Delete the repository from its settings if you want it gone. |
| `pick between 1 and 200 repositories` | One move takes between 1 and 200 repositories. |

A move runs on the server and survives closing the page. Reopen Moving to Sailfork on the organization or the migrate page to see where it is.

## Access and invitations

### I was invited but cannot join

If the invitation went to an email address, you see `verify <address> first; the invitation went to that address`. Verify that address under Settings, Account. An invitation expires after 7 days, and an expired, revoked or answered one says `that invitation is not waiting for you; it may have expired, been revoked or been answered`. Ask an owner to send it again. See [Organizations](https://sailfork.com/docs/organizations#answer-an-invitation).

### I cannot see a repository that a teammate can

Your level on it may be none. In an organization, check the base access and the teams you are in, and whether the organization requires a second step. See [Roles and permissions](https://sailfork.com/docs/permissions).

### `has blocked you, so you cannot open or comment on issues and pull requests here`

An owner blocked your account from that repository. You can still read public code. See [Roles and permissions](https://sailfork.com/docs/permissions#blocked-people).

---

Every docs page: https://sailfork.com/llms.txt
