Operate

Troubleshooting

Symptoms, causes and fixes for installation, login, instances, storage, SSH and billing.

First steps

Run clockingcloud doctor. It checks the version, credentials and connectivity.
Re-run the failing command with --debug to see request metadata. Credentials are redacted.
Check clockingcloud logs <name> --since 15m and clockingcloud status <name> for the instance.
If you contact support, include the request_id from the error.

Installation and login

Symptom	Cause	Fix
`command not found: clockingcloud`	Homebrew bin is not on PATH.	Run `brew --prefix` and add its `bin` directory to PATH.
`No available formula`	The tap is not added or not trusted.	Use the full name: `brew install clockingcloud/tap/clockingcloud`.
Browser does not open on `clockingcloud login`	No browser available.	Use `clockingcloud login --device` or `--no-browser`.
Exit code 3 / `unauthenticated`	Expired or revoked key, or a stale `CLOCKINGCLOUD_API_KEY` is overriding your login.	Run `env \| grep CLOCKINGCLOUD_`, unset it, then `clockingcloud whoami`.
Cannot reach the API	Proxy or firewall.	Set `HTTPS_PROXY`, and allow outbound 443 to www.clockingcloud.com.

Instances

Symptom	Cause	Fix
Stuck in `provisioning`	Waiting for GPU capacity, or a long `setup` step.	Check `clockingcloud logs`. If capacity, retry or use `gpu: auto`. Reduce setup work by baking files into a volume.
Moved to `failed` during setup	A `setup` command exited non-zero.	Reproduce for free with `clockingcloud dev`. The GPU was released automatically.
First request is slow	Cold start and first-time weight load.	Expected once per model per node. Use `scale.min: 1` if you need always-warm, and `clockingcloud trace` to see the split.
Instance stopped by itself	`idle_timeout` elapsed, or credit reached zero.	Check `clockingcloud balance` and `clockingcloud logs`. Raise `idle_timeout` if it is too short.
Out of memory	Resolution or clip length too large for the GPU.	Choose a larger `gpu`, raise `gpus`, or reduce size.
Output differs between runs	No fixed seed or a different GPU type.	Pass `--seed`, and pin `gpu` for reproducibility.

Storage

Symptom	Cause	Fix
`Bucket URI should start with s3://`	Wrong scheme for the provider.	Use `s3://`, `azure://` or `gs://`.
Access denied on a connected bucket	Missing or under-privileged secrets.	Set the secrets listed in Storage and grant list and get on the bucket.
Mounted folder is empty	Wrong prefix, wrong volume name, or the file was just uploaded.	Check `clockingcloud volume ls` and the `path`. Changes in your bucket can take up to a minute to appear.
Cannot write to `/data`	Mounted `ro`.	Use `mode: rw`, or write to a different volume.
`You already have a volume with that name`	Names are unique per account.	Pick another name or remove the old volume.
Size rejected	Size outside 10 to 10,000 GB or not a whole number.	Use a whole number from 10 to 10000.

SSH

Symptom	Cause	Fix
`Permission denied (publickey)`	Key not on your account, or a key added after the replica started.	Check `clockingcloud ssh-key ls`. Restart with `clockingcloud stop` and `clockingcloud start`, or let a new replica start.
`Paste a public key that starts with ssh-ed25519...`	You uploaded the private key or the wrong file.	Add the `.pub` file.
`That key is already added`	The fingerprint is already on your account.	Nothing to do.
`UNPROTECTED PRIVATE KEY FILE`	Private key permissions too open.	`chmod 600 ~/.ssh/id_ed25519`.
Connection refused	Instance is not `running`.	Check `clockingcloud status`, then `clockingcloud start`.

Billing

Symptom	Cause	Fix
Exit code 4 / `insufficient_credits`	Balance is zero.	Add credit in the console, then `clockingcloud start <name>`.
Paid but balance did not change	Checkout was not completed, or the page was closed early.	Open Billing again. Completed payments are credited once. If still missing after a few minutes, contact support with the receipt.
Spend is higher than expected	`scale.min` above 0, high `scale.max`, or a long `idle_timeout`.	Run `clockingcloud usage --by instance` and `clockingcloud top`. Lower those values and use `clockingcloud plan`.

Contact support

Email hello@clockingcloud.com with your account email, the instance or request ID, the exact command, and the output of clockingcloud doctor. Never include API keys or secrets.

Something unclear or missing? Email hello@clockingcloud.com.