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 30m

Server creation fails

Symptom: gibil create fails with an error.

Common causes:

Error	Cause	Fix
`401 Unauthorized`	Invalid provider token	Re-run `gibil init --provider <name> --token <new-token>`
`429 Too Many Requests`	Provider 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	Run `gibil providers` to see valid sizes and regions for each cloud

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: Your provider 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 (across every configured provider)
gibil destroy --all

# Then check the relevant cloud console manually:
# Hetzner: Servers + Security → SSH Keys → delete any gibil-* resources
# Vultr:   Products → Cloud Compute + Account → API → SSH Keys → delete any gibil-* resources

Always run gibil destroy --all before checking your cloud 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 your provider console

Next steps

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

Troubleshooting

On this page