Troubleshooting

SSH connection timeout

Symptom: gibil ssh or gibil run hangs or times out.

Causes:

Cloud-init is still running — the VM is booting but SSH isn't ready yet
Firewall blocking port 22
The server was auto-destroyed (TTL expired)

Fix:

# Check if the server still exists
gibil list

# If it exists, wait a bit — cloud-init takes ~60-120s after create
gibil run my-app "echo hello"

# If TTL expired, create a new server
gibil create --name my-app-2 --ttl 30

Server creation fails

Symptom: gibil create fails with an error.

Common causes:

Error	Cause	Fix
`401 Unauthorized`	Invalid Hetzner token	Run `gibil auth setup --token <new-token>`
`429 Too Many Requests`	Hetzner rate limit	Wait 60 seconds and retry
`409 Conflict`	SSH key name already exists	Destroy the old instance first, or use a different name
`422 Unprocessable`	Invalid server type or location	Check Configuration for valid options

Cloud-init tasks failed

Symptom: .gibil-tasks-failed exists instead of .gibil-tasks-done.

Debug:

# SSH in and check the log
gibil ssh my-app
cat /var/log/cloud-init-output.log | tail -50

# Check which task failed
cat /root/.gibil-tasks-failed    # shows the failed task name

Common causes: pnpm install fails due to missing native deps, wrong Node version, or private npm packages.

Repo not cloned

Symptom: /root/project doesn't exist or is empty.

Causes:

--repo URL is incorrect or inaccessible
Private repo without GITHUB_TOKEN set
Cloud-init hasn't reached the clone step yet

Fix:

# Check cloud-init progress
gibil run my-app "cat /var/log/cloud-init-output.log | grep -i clone"

# For private repos, ensure GITHUB_TOKEN is available
gibil run my-app "echo \$GITHUB_TOKEN"

Server name already taken

Symptom: gibil create --name my-app fails because my-app already exists.

Fix:

# Check existing instances
gibil list

# Destroy the old one
gibil destroy my-app

# Or use a different name
gibil create --name my-app-2

Orphaned resources

Symptom: Hetzner console shows VMs or SSH keys that gibil list doesn't.

This can happen if a gibil destroy was interrupted or the CLI crashed.

Fix:

# Destroy all tracked instances
gibil destroy --all

# Then check Hetzner console manually:
# 1. Servers → delete any gibil-* servers
# 2. Security → SSH Keys → delete any gibil-* keys

Always run gibil destroy --all before checking the Hetzner console. The CLI tracks servers locally in ~/.gibil/instances/ — if files were deleted manually, the CLI won't know about orphaned servers.

Reset local state

If your local Gibil state gets corrupted:

# Remove all local metadata (does NOT delete remote servers)
rm -rf ~/.gibil/instances ~/.gibil/keys

# Then destroy any remaining servers via Hetzner console

Next steps

Hetzner Setup — verify your setup
Configuration — check your .gibil.yml

Troubleshooting

On this page