> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors

> What each CLI error means and what to do about it.

## Connection error

```text theme={null}
Could not connect to JoyStream API at http://localhost:8000.
```

The CLI couldn't reach the backend. The message names the URL it tried, which is usually the fastest clue.

Check which URL it's using:

```bash theme={null}
echo $JOYSTREAM_API_URL
```

If that's empty, the CLI falls back to `config.toml` `[backend].port`, then to `http://localhost:8000`. Point it at the right place:

```bash theme={null}
export JOYSTREAM_API_URL=https://api.example.com
jstm whoami
```

See [Configuration](/cli/configuration) for the full precedence.

## Session expired

```text theme={null}
Session expired
Run joystream login to sign in again.
```

Your token was rejected or has expired. The CLI refreshes proactively when a token is within 60 seconds of expiring; this appears when the refresh didn't happen or the server rejected the token.

```bash theme={null}
jstm login
```

If it recurs immediately after logging in, you may be logging into one instance and running against another. Check that `JOYSTREAM_API_URL` and `JOYSTREAM_CONFIG_DIR` point at the same instance.

## Permission errors

A `403` shows the status and detail rather than a login message. That is intentional — you are signed in, but not permitted.

Common causes:

| Command                                                  | Requires                                                                    |
| -------------------------------------------------------- | --------------------------------------------------------------------------- |
| `vault audit`, `vault scope`                             | Org owner or admin                                                          |
| `workspace member-add`, `member-update`, `member-remove` | Owner or admin in that workspace                                            |
| Sharing an agent or run                                  | Owner or admin in a team workspace; any non-viewer role in an org workspace |
| `admin create-user`, `admin delete-user`                 | A `service_role_key` in `config.toml`                                       |

Signing in again won't help. Check your role:

```bash theme={null}
jstm workspace members acme-corp/finance
```

## Could not determine active workspace

Commands that operate on a workspace need one, either from `--workspace` or from your context.

```bash theme={null}
jstm whoami
jstm workspace list
jstm workspace switch acme-corp/finance
```

Some commands require `--workspace` explicitly rather than defaulting — the `connection` group is the main one, because credential resolution depends on which workspace is asking.

## Requires an interactive terminal

```text theme={null}
jstm agent plan requires an interactive terminal.
```

The planning chat won't run in a pipe, in CI, or with captured output. There is no line-mode fallback.

Run it in a normal terminal, or create the draft non-interactively:

```bash theme={null}
jstm agent plan --new --json
```

## Specify a form: --new or an id

You ran a bare `jstm agent plan`. Creating an agent is always explicit.

```bash theme={null}
jstm agent plan --new                # create
jstm agent plan 5f3a5c81-…           # resume
jstm agent plan list                 # find a lost session id
```

This exits `2`, not `1` — it's a usage error.

## Ambiguous workspace handle

Team handles are unique within an organization, not across all of them.

```bash theme={null}
jstm workspace resolve platform                  # every match
jstm workspace resolve platform --org acme-corp  # scoped
```

Use the fully qualified form, `acme-corp/platform`, to be unambiguous.

## Multiple credentials for a provider

```bash theme={null}
jstm connection remove slack --workspace acme-corp/finance
```

If several credentials exist, the command asks you to name one rather than guessing. List them and pass `--id`:

```bash theme={null}
jstm connection list --workspace acme-corp/finance
jstm connection remove slack --workspace acme-corp/finance --id 4d90c7e2-…
```

## Seeing the full error

```bash theme={null}
JOYSTREAM_DEBUG=1 jstm agent run failed-payment-digest
```

This logs the full traceback to stderr. Because diagnostics go to stderr and results to stdout, you can debug and pipe at the same time:

```bash theme={null}
JOYSTREAM_DEBUG=1 jstm agent list --json 2>debug.log | jq .
```

## See also

* [Credential problems](/troubleshooting/credentials)
* [Blocked or failing runs](/troubleshooting/runs)
* [Conformance failures](/troubleshooting/conformance)