Troubleshooting

Tarsail tries to fail with a specific area tag such as [config:target], [remote:ssh], or [compose:image].

Use the tag to locate the failing layer: config, local Docker, SSH, remote Docker, file transfer, image loading, or Compose startup.

Config file not found

Symptom:

[config:load] Config file not found: tarsail.yml

Fix:

tarsail init

or pass the intended file:

tarsail --config tarsail.production.yml doctor

Unknown or unsupported config key

Symptom:

[config:parse] Unknown top-level config key

or:

[config:scope] Unsupported Phase 0 config section: targets

Fix: use only supported Phase 0 top-level keys:

project
target
compose
deploy
files
secrets

Tarsail intentionally rejects future-looking sections until they have real behavior.

Compose service has no image tag

Symptom:

[compose:image] Service "web" has a build section but no explicit image tag.

Fix:

services:
  web:
    build: .
    image: my-app-web:${TARSAIL_RELEASE_ID:-local}

Then rerun:

tarsail doctor

Docker command not found

Symptom:

[local:docker] Docker command not found.

Fix:

• install Docker Engine or Docker Desktop;
• ensure docker is on PATH;
• restart the terminal after installation.

Verify:

docker ps
docker compose version

Docker daemon is not reachable

Symptom:

Docker daemon reachable: FAIL

Fix:

• start Docker Desktop or Docker Engine;
• confirm your user can access Docker;
• on Linux, confirm group or sudo policy;
• on Windows, confirm Docker Desktop is running in the expected backend.

Verify:

docker ps

SSH connection fails

Symptom:

[remote:ssh] Remote command failed

Check direct SSH first:

ssh deploy@example.com

If using a key:

ssh -i ~/.ssh/my-app-deploy-key deploy@example.com

Then run:

tarsail --identity-file ~/.ssh/my-app-deploy-key doctor

Common causes:

• wrong target.host;
• wrong target.user;
• wrong target.port;
• server firewall blocks SSH;
• cloud provider security group blocks SSH;
• private key path is wrong;
• password login is disabled;
• host key is not trusted.

Password mode says known_hosts cannot be loaded

Symptom:

[remote:ssh] Could not load SSH known_hosts file

Fix:

ssh deploy@example.com

Accept the host key only after verifying it. Then rerun:

tarsail --ask-password doctor

Password authentication fails

Symptom:

Password authentication failed

Check:

• the password is correct;
• the server permits password authentication;
• the configured user is allowed to log in;
• the server is not closing password sessions due to rate limits or security policy.

If password login is disabled, use an SSH key.

Target path is rejected

Symptom:

[config:target] target.path is too broad

Fix:

target:
  path: /opt/my-app

Do not use broad paths such as /opt, /var, /home, /root, or /tmp.

Target path is not writable

Symptom:

target path writable: FAIL

Fix on the server:

sudo mkdir -p /opt/my-app
sudo chown deploy:deploy /opt/my-app

Then:

tarsail doctor

If deploying as root, confirm the path is not blocked by permissions or a read-only filesystem.

Shared env file is missing

Symptom:

shared files available: FAIL

If compose.env_file.source is omitted, Tarsail expects the remote file to already exist:

compose:
  env_file:
    target: shared/.env

Create it on the server or add a local source:

compose:
  env_file:
    source: .deploy/prod.env
    target: shared/.env

Secret source is missing

Symptom:

[config:secrets] secrets[0].source is not available

Fix:

• create the local file;
• correct the path;
• keep the path relative to the config file;
• use forward slashes.

Example:

secrets:
  - source: .deploy/app.key
    target: shared/secrets/app.key

Image is not available locally

Symptom:

[docker:image] Image is not available locally

Tarsail discovered an image in Compose but could not find it after build.

Fix:

docker compose -p my-app --env-file .deploy/prod.env -f compose.yaml build
docker image ls
tarsail deploy

For images without build:, pull them locally:

docker pull nginx:1.27-alpine

Remote Docker is unavailable

Symptom:

Docker available: FAIL

Check on the server:

docker ps
docker compose version

Fix:

• install Docker;
• install Docker Compose v2;
• start the Docker daemon;
• add the deploy user to the Docker group if appropriate;
• reconnect after changing group membership.

Compose starts but public access fails

If tarsail deploy succeeds and containers are running, the remaining issue may be outside Tarsail.

Check on the server:

cd /opt/my-app
docker compose -p my-app --env-file current/.tarsail.env --env-file shared/.env -f current/compose.yaml ps
curl -v http://127.0.0.1:8080/healthz
ss -ltnp

Check from your local machine:

curl -v http://example.com/healthz

Common causes:

• wrong published port in Compose;
• application listens on 127.0.0.1 inside the container instead of 0.0.0.0;
• OS firewall blocks the port;
• cloud provider security group blocks the port;
• DNS points to a different IP;
• reverse proxy config expects HTTPS or a different host;
• another service already owns the port.

Port already in use

Symptom from Compose:

bind: address already in use

Check on the server:

ss -ltnp | grep ':80'

Fix one of:

• stop the conflicting service;
• change the Compose published port;
• route through an existing reverse proxy;
• remove old orphan containers if they are from a previous Compose shape.

Deployment fails after activation

Symptom:

Deployment failed after activation.
Run "tarsail rollback" to restore the previous release.

Run:

tarsail rollback
tarsail logs --tail 300

Then inspect the failed release manually if needed:

ssh deploy@example.com
cd /opt/my-app
ls -la releases
cat current/manifest.json

Remember that rollback does not undo database migrations or Docker volume changes.