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

# Troubleshooting

> Diagnose common TalkValue CLI failures: auth errors, missing IDs, rate limits, network issues, and import mapping problems.

Every CLI failure leaves three pieces of evidence: an exit code, an error message on stderr, and the command you ran. The patterns below match the most common failure modes to a symptom, a cause, and a fix.

<Note>
  **Quick reference:** see [Exit codes](/cli/exit-codes) for the full code table. The error message envelope on stderr is documented in [Output format](/cli/output-format).
</Note>

## Authentication failures (exit `3`)

### Symptom: "Not logged in. Run 'talkvalue auth login' to authenticate."

```bash theme={null}
$ talkvalue path person list
Not logged in. Run 'talkvalue auth login' to authenticate.
$ echo $?
3
```

**Cause:** no `TALKVALUE_TOKEN` is set in the environment and no saved profile exists for the current shell.

**Fix:**

```bash theme={null}
# Interactive (laptop)
talkvalue auth login

# Non-interactive (CI, scripts, agents)
export TALKVALUE_TOKEN=<your-token>
```

See [Authentication](/cli/authentication) for the full credential precedence and multi-profile workflow.

### Symptom: "Session expired. Run 'talkvalue auth login' to re-authenticate."

The OAuth profile exists but the refresh token has lapsed.

**Fix:**

```bash theme={null}
talkvalue auth login
```

Re-runs the device flow and refreshes the credential stored in your system keyring.

### Symptom: "Server did not return a refresh token. Please try logging in again."

A login race or revoked session prevented the server from issuing a refresh token.

**Fix:** re-run `talkvalue auth login`. If it persists, sign out first to clear local state:

```bash theme={null}
talkvalue auth logout
talkvalue auth login
```

### Symptom: "Device code expired before authorization"

The sign-in code from `auth login` was not approved in the browser before its TTL elapsed.

**Fix:** run `talkvalue auth login` again and approve the code promptly.

### Symptom: "Multiple organizations available. Use --org \<name-or-id> to select one."

Your account belongs to more than one organization and the login flow can't pick one.

**Fix:**

```bash theme={null}
talkvalue auth login --org "Acme Inc."
# or
talkvalue auth login --org org_01HXXX...
```

## Not found (exit `4`)

### Symptom: "\<entity> \<id> not found"

```bash theme={null}
$ talkvalue path person get 999999
Person 999999 not found.
$ echo $?
4
```

**Cause:** the resource (person, event, channel, company, tag, or import job) doesn't exist in the active organization. Wrong ID, wrong organization, or the record was deleted.

**Fix:**

1. Confirm the active organization with `talkvalue auth status`.
2. Switch organizations if needed: `talkvalue auth switch "Other Org"`.
3. List the resource to confirm the ID:
   ```bash theme={null}
   talkvalue path person list --keyword "alice@acme.com" --json
   talkvalue path event list --json
   talkvalue path channel list --json
   ```

## Forbidden (exit `5`)

### Symptom: a `5` exit code with a permission-style message

```bash theme={null}
$ talkvalue path person delete 142
Forbidden. Your role does not allow this action.
$ echo $?
5
```

**Cause:** you're authenticated and the resource exists, but the active organization's role doesn't permit the operation.

**Fix:**

* Ask an organization admin to grant the necessary role.
* Confirm you're authenticated as the correct identity with `talkvalue auth status`.

See [Roles and permissions](/administration/workspace/roles-and-permissions) for what each role allows.

## Usage errors (exit `2`)

### Symptom: a required flag is missing

```bash theme={null}
$ talkvalue path import create --source-id 7 --mode UPDATE
Creating an import requires --file-key
$ echo $?
2
```

**Cause:** a required option was omitted.

**Fix:** read the error message. It names the missing flag. The full required-flag list for every command lives on its leaf page. For `import create`, see [`import create`](/cli/commands/path/import/create).

### Symptom: an enum value is invalid

```bash theme={null}
$ talkvalue path import create --file-key abc --source-id 7 --mode REPLACE --mapping 0:EMAIL
--mode must be one of: UPDATE, SKIP
$ echo $?
2
```

**Cause:** you passed a value that isn't in the allowed set.

**Fix:** use one of the values the error names. `import create` accepts `UPDATE` or `SKIP`; other commands list their allowed values in the error and on the leaf page.

### Symptom: out-of-range argument count

```bash theme={null}
$ talkvalue path analysis channel audience --channel-id 7
--channel-id requires between 2 and 5 channel IDs
$ echo $?
2
```

**Cause:** an option that takes a bounded number of arguments received too few or too many.

**Fix:** match the count to the bound. `audience` accepts 2 to 5 `--channel-id` flags; others bound themselves similarly.

### Symptom: "File not found" or "Permission denied" on `import analyze`

```bash theme={null}
$ talkvalue path import analyze --file ./missing.csv
File not found: ./missing.csv
$ echo $?
2
```

**Cause:** the CSV path doesn't exist or isn't readable by the current user.

**Fix:** confirm the path with `ls`, fix permissions with `chmod`, or pass an absolute path.

### Symptom: "Unsupported output format"

```bash theme={null}
$ talkvalue path person list --format xml
Unsupported output format: xml
$ echo $?
2
```

**Cause:** `--format` accepts only `json`, `table`, or `csv`.

**Fix:** use one of the three. See [Output format](/cli/output-format).

## Network and rate-limit failures (exit `1`)

### Symptom: "Request failed with status 429"

You hit the API rate limit.

**Fix:** the CLI already retries `429`, `502`, `503`, and `504` automatically with exponential backoff, and honors the server's `Retry-After` header up to 60 seconds. If you still see a `429` after retries, slow your script:

```bash theme={null}
# In a loop, sleep between calls
for id in 1 2 3 4 5; do
  talkvalue path person get "$id"
  sleep 1
done
```

### Symptom: "Request failed with status 5xx" or timeout

```bash theme={null}
$ talkvalue path person list
Request failed with status 503
$ echo $?
1
```

**Cause:** transient server-side failure or network timeout. The CLI retries up to three times before surfacing the error.

**Fix:**

1. Wait and retry. `5xx` errors usually self-heal in seconds.
2. Check the API status at [status.trytalkvalue.com](https://status.trytalkvalue.com).
3. If you're overriding the API host, confirm `TALKVALUE_API_URL` and `--api-url` point at the right environment.

### Symptom: a generic network error or `TypeError`

A transient connectivity issue between your machine and the API.

**Fix:** the CLI auto-retries network failures. If it persists, check your proxy or VPN configuration, then re-run.

## CSV import problems

### Symptom: "Creating an import requires at least one --mapping"

You skipped the mapping step.

**Fix:** run `import analyze` first to see the suggested mapping, then pass it back to `import create`:

```bash theme={null}
FILE_KEY=$(talkvalue path import analyze --file ./contacts.csv --json | jq -r '.data.fileKey')
talkvalue path import create \
  --file-key "$FILE_KEY" \
  --source-id 7 \
  --mode UPDATE \
  --mapping 0:EMAIL --mapping 1:FIRST_NAME --mapping 2:LAST_NAME
```

See [Recipe: CSV import](/cli/recipes/csv-import) for the full flow and [Column mapping](/path/import/column-mapping) for the target-field reference.

### Symptom: job status is `PARTIAL_SUCCESS` and `failedCount > 0`

Some rows imported, some were rejected.

**Fix:** export the rejected rows, fix the data, and re-import:

```bash theme={null}
talkvalue path import failed-export "$JOB_ID" > "failed-$JOB_ID.csv"
# Inspect failed-<id>.csv — header is rowNum,errorCode,errorMessage,rawValue
# Fix the bad rows, then re-run import create on the corrected file
```

Common `errorCode` values:

* `INVALID_EMAIL`: the email column has a malformed value. Fix the address.
* `MISSING_REQUIRED`: the email column is empty for that row. Add an email or drop the row.

### Symptom: job status is `FAILED` and `processedRows` is `0`

The whole job failed before any rows landed. Usually a malformed file, an invalid `fileKey`, or a source-channel permission issue.

**Fix:**

1. Re-run `import analyze`. It returns a fresh `fileKey` and surfaces file-level errors.
2. Confirm the `source-id` channel exists and you have access: `talkvalue path channel get <id>`.
3. Reduce the file to the first 10 rows and retry to isolate which rows trigger the failure.

## Unexpected output

### Symptom: `--json` or `--format` was ignored on an export command

```bash theme={null}
$ talkvalue path event person export 18 --json > out.json
Warning: export commands always output CSV regardless of --format
```

**Cause:** export commands (`person export`, `event person export`, `channel export`, `import failed-export`) always stream raw CSV. They ignore the global format flags.

**Fix:** drop `--json` / `--format` and consume the CSV directly, or use the matching `list` command if you specifically need JSON.

### Symptom: colored output in CI logs

ANSI color codes are leaking into a log aggregator that can't render them.

**Fix:**

```bash theme={null}
export NO_COLOR=1
# or
talkvalue path person list --no-color
```

See [Environment variables](/cli/environment-variables) for the full color-control reference.

## Still stuck?

* Run any command with `--help` for the full flag list.
* Check the latest CLI version: `talkvalue update`.
* Email [support@trytalkvalue.com](mailto:support@trytalkvalue.com) with the exact command, the stderr message, and the exit code from `echo $?`.

## Related

* [Exit codes](/cli/exit-codes). Full table.
* [Output format](/cli/output-format). Error envelope shape on stderr.
* [Authentication](/cli/authentication). Credentials, profiles, and `TALKVALUE_TOKEN`.
* [Environment variables](/cli/environment-variables). Every env var the CLI reads.
* [Recipe: CSV import](/cli/recipes/csv-import). Happy-path import workflow with failure recovery.