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

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.

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:

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.

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.

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.

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

The account is suspended. Use the contact page.

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.

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 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:

sailfork auth setup-git

A token whose owner has a different handle than the username is refused. See Access 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.

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.

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.

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.

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.

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.

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.

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.

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?

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.

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.

Do commit hashes change?

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

Errors during a move

MessageWhat to do
connect your GitHub account firstConnect GitHub under Settings, Sign-in and sessions, Connected accounts.
this GitHub installation is not connected to your accountPick 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 GitHubThe GitHub App cannot reach the repository. Check that the installation includes it.
archiving <org>/<name> needs admin access to it on GitHubChoose an option other than archive for what happens to the original, or ask someone with admin access on GitHub.
<name> already existsYou already have a repository with that name here. Rename one.
<org>/<name> is already being moved, or its name is takenA move for that repository is already running, or the name is used.
the copy is not ready to switchWait until the copy shows ready, then switch.
this repository already lives on Sailfork; delete it from its settingsYou tried to cancel a move that already switched. Delete the repository from its settings if you want it gone.
pick between 1 and 200 repositoriesOne 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.

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.

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.

Loading Sailfork