Skip to main content
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.
Quick reference: see Exit codes for the full code table. The error message envelope on stderr is documented in Output format.

​
Authentication failures (exit 3)

​
Symptom: “Not logged in. Run ‘talkvalue auth login’ to authenticate.”

$ 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: 
# Interactive (laptop)
talkvalue auth login

# Non-interactive (CI, scripts, agents)
export TALKVALUE_TOKEN=<your-token>
See 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: 
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: 
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: 
talkvalue auth login --org "Acme Inc."
# or
talkvalue auth login --org org_01HXXX...

​
Not found (exit 4)

​
Symptom: “<entity> <id> not found”

$ 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: 
    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

$ 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 for what each role allows.

​
Usage errors (exit 2)

​
Symptom: a required flag is missing

$ 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.

​
Symptom: an enum value is invalid

$ 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

$ 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

$ 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”

$ 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.

​
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: 
# 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

$ 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.
  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: 
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 for the full flow and 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: 
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

$ 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: 
export NO_COLOR=1
# or
talkvalue path person list --no-color
See 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 with the exact command, the stderr message, and the exit code from echo $?.