# CLI troubleshooting (/docs/cli/troubleshooting)



## Command not found [#command-not-found]

Confirm the package is installed and that the global package binary directory is on `PATH`:

```sh
ivk --version
invokeable --version
```

If neither command exists, reinstall from npm. Restart the shell only if the package manager changed `PATH`.

## Invokeable is not configured [#invokeable-is-not-configured]

Official production releases contain production connection defaults. For a controlled custom environment, set:

```sh
ivk config set endpoint "<endpoint from Invokeable>"
ivk config set client-id "<client ID from Invokeable>"
ivk config set app-url https://app.example.com
```

Use only values supplied by an Invokeable administrator. Do not copy production credentials into staging.

## Sign-in does not open a browser [#sign-in-does-not-open-a-browser]

Run:

```sh
ivk login --no-browser
```

Open the printed verification URL yourself and enter the code. If the code expires, run the command again. Do not reuse an expired code.

## Wrong workspace [#wrong-workspace]

```sh
ivk ws list
ivk ws switch org_123
ivk whoami
```

Use the organization ID from the current list.

## Invalid JSON or missing field [#invalid-json-or-missing-field]

Validate that `--input` contains one JSON object. Use `--field name=value` for short values. The CLI reports stable codes such as `INPUT_JSON_INVALID`, `INPUT_FIELD_INVALID`, `INPUT_FIELD_MISSING`, and `INPUT_FIELD_UNEXPECTED`.

## Permission denied [#permission-denied]

Run `ivk access current` and `ivk whoami`. The active role sets the maximum permission. A scoped evidence restriction or approval requirement may add another condition.

Ask an Admin for the smallest needed access. Do not switch to a more privileged token as a workaround.

## A destructive action requires confirmation [#a-destructive-action-requires-confirmation]

Read the command and input again, then repeat with `--yes` only when the target is correct. The confirmation requirement protects archive, revoke, stop, remove, deactivation, and deletion operations.

## A run timed out while waiting [#a-run-timed-out-while-waiting]

A wait timeout does not prove that the assessment failed or stopped. Use the returned plan ID:

```sh
ivk r progress plan_example
ivk r list
```

Check current state before retrying any state-changing operation.

## JSON output contains an error [#json-output-contains-an-error]

Use the stable error code and exit status. Do not parse raw messages for control flow. Unknown failures use a safe fallback instead of exposing a provider response or stack trace.

## Credential command fails [#credential-command-fails]

Confirm the connection is waiting for a credential and that you used its product-connection ID. The secret file must contain a nonempty value. The CLI removes one trailing newline before sealing it.

For product-level problems, see [General troubleshooting](/docs/reference/troubleshooting).