# Troubleshooting

> What to check when sign-in, a launch, a running job, outputs or billing do not behave as you expect.

Source: https://nodus-platform-site.pages.dev/docs/reference/troubleshooting/
Build revision: 211ad9f836655b1c3a2668c4693e442471f28614

Start with the object itself. `nodus describe <kind>/<name>` shows its phase, conditions, recent events, attempts and cost so far, and every error names a code with a fix and a docs link. When you contact support, include the `requestId` from the error.

## Signing in

* **The browser never opens.** Run `nodus login --device` and approve the code from any device.
* **A CI machine needs a key.** Create an API key in the console (or a ServiceAccount key) and pipe it in: `echo "$NODUS_API_KEY" | nodus login --with-token`. `NODUS_API_KEY` alone also works.
* **The wrong org or project.** `nodus whoami` prints the principal, org, project and scopes in use. `nodus config get-contexts` lists every org you signed in to and `nodus config use-context` switches between them.

## A launch is refused

|Code|Meaning|What to do|
|-|-|-|
|`InsufficientCredits` (402)|The hold for this launch is larger than your available credit|Top up with `nodus billing top-up <usd>`, or lower `--max-cost`|
|`BudgetExceeded` (402)|A budget that covers this object would be exceeded|Raise the budget or launch in a project it does not cover|
|`QuotaExceeded` (429)|An org or project quota is reached|`nodus get quotas`; starter limits lift at your first purchase|
|`CapacityUnavailable` (503)|No offering matches the requirements right now|Allow more accelerators or regions, or wait for the ETA in the message|
|`Invalid` (422)|The spec fails validation|The message names each field; `nodus explain job.spec` documents them|

Every code has its own page under [Error codes](https://nodus-platform-site.pages.dev/docs/reference/errors/).

## A job does not start

* **`Pending` for a long time.** `nodus describe job/<name>` shows why under Conditions and Events, including the offerings considered and why others were rejected.
* **The image fails to pull.** Check the image reference and, for a private registry, the pull Secret it names.

## A job fails or stops

* **The command exits non-zero.** `nodus logs job/<name>` shows your program’s output; the phase is `Failed` with the exit code. `nodus run` exits with the same code.
* **It stopped when credit ran out.** A running job stops gracefully inside its reserved amount and reports it in its conditions. Add credit and it resumes from its last checkpoint.
* **The CLI itself failed.** Exit code `125` is a Nodus or API error and `124` a timeout, never your program’s.

## Outputs and checkpoints

* **An output is missing.** Only paths declared with `--output NAME=/path` (or `spec.outputs`) are collected. List them with `nodus get job/<name> -o jsonpath='{.status.outputs}'`.
* **A resumed job started from scratch.** Nodus restores the files your program saved in its checkpoint directory (`NODUS_CHECKPOINT_DIR`); your program must load them on start. Restoring files does not restore process memory.

## Billing

* **A charge looks higher than the run time.** Rented machines bill from creation to confirmed deletion, including start-up and shutdown. `nodus get usage --field-selector object.name=<name> --group-by segment` itemizes it.
* **Where did my credit go?** `nodus billing` shows available credit, open holds and budgets; `nodus get usage --group-by project` breaks spending down.