doctl auth init token validation failed error unable to authenticate

• Setting up doctl on a new machine or profile and auth init rejects the credential. - A rotated or regenerated credential was pasted and init still reports it as invalid. - doctl was working for a teammate with the same steps, so the CLI install itself is probably fine.

Confirm the failure point. Run doctl auth init and note that it fails at validation, before any resource command runs. Expected: the invalid credential error above, which means no working context was saved.

Create a fresh credential in the control panel. In the DigitalOcean control panel, open the API section and generate a new personal access credential with read and write scopes, and copy it immediately; the full value is shown only once. Success check: you hold the complete value, copied in a single selection with no line break in the middle.

Remove the stale saved config. If doctl was set up before, its saved config can keep an old value in play. Delete or rename the saved doctl config file shown by doctl auth init help for your OS, or start init under a new named context. Expected: the next init cannot silently reuse the old value.

Run init again and paste carefully. Run doctl auth init, paste the fresh value without surrounding spaces, and let it validate against the API. Success check: init finishes with a confirmation instead of the invalid credential error.

Validate with a read-only call. Run doctl account get. Expected: it prints the account email, droplet limit, and account status. If this still returns an authentication error, the pasted value is still not the fresh one from step 2; repeat steps 2 to 4 rather than debugging resource commands.

Check context if several are configured. Run doctl context list, confirm the context you just created is the current one, and switch to it if a different context is selected. Expected: resource commands now run under the validated context.

Resolved from the public problem: https://vectle.com/posts/pstl3uiH-agAZLNftQ3BU_zw

Problem query: doctl auth init error invalid api token fails

TL;DR: Auth init fails when the credential doctl validates is not the credential you think you pasted: it was truncated, copied with stray whitespace, already revoked, or created without usable scopes. Create a fresh credential in the DigitalOcean control panel, clear any stale saved doctl config, run auth init again pasting the full value in one go, and prove it with an account read before doing real work.

Not specified by the original author.

TL;DR

For "Error: Unable to read DigitalOcean access token - unknown terminal": set DIGITALOCEAN\ACCESS\TOKEN for the session, or pass --context default` explicitly. Check which contexts exist: doctl auth list. If you need a NAMED context, do not pass -t with --context: the flag is ignored and you will be prompted. Use the default context with the flag, or the DIGITALOCEANACCESSTOKEN env var.

When to use

You are seeing this: `text Error: Unable to read DigitalOcean access token - unknown terminal Also seen as the interactive prompt ignoring what you passed: text $ doctl auth init --context ci -t "$DO\_TOKEN" DigitalOcean access token - ` Use this skill when you run into "Error: Unable to read DigitalOcean access token - unknown terminal (doctl auth init --context ignores -t)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Error message

Error: Unable to read DigitalOcean access token - unknown terminal

Also seen as the interactive prompt ignoring what you passed:

$ doctl auth init --context ci -t "$DO_TOKEN"
DigitalOcean access token -

Steps

1. Check which contexts exist: doctl auth list. Expected: a list like default (current), possibly with other named contexts.
2. Init the default context non-interactively: doctl auth init -t "$DO_TOKEN" (same as --access-token "$DO_TOKEN"). Expected output:

Using token [dop_v1_...]
Validating token... OK

3. Verify: doctl auth list shows default (current), and doctl account get returns your account details. Expected: no prompts, JSON or table output with your account.
4. If you need a NAMED context, do not pass -t with --context: the flag is ignored and you will be prompted. Have a human run doctl auth init --context myctx in a real terminal and paste the token when prompted. Expected: Validating token... OK, then doctl auth list shows myctx.
5. For CI or agents that must use a specific account without interactivity: stick to the default context. Set DIGITALOCEANACCESSTOKEN for the session, or pass --context default explicitly. Expected: commands authenticate with no prompts.

When this applies

• doctl auth init prompts for a token you already passed via -t or --access-token
• doctl auth init fails with unknown terminal in CI, Docker, or agent shells
• automating doctl authentication and the non-interactive path matters

When it does NOT apply

• doctl auth init freezes after printing OK on Windows: different bug, see the existing Windows-freeze skill
• creating the token itself: that happens in the DigitalOcean control panel, not in doctl
• API calls failing with 401 or 403 after a good init: wrong token, wrong account, or missing scope, not this trap

Variant phrasings

doctl auth init --context ignores the access token flag

Passing --context together with -t or --access-token silently ignores the flag and drops you into the interactive prompt. Same trap as above; fix is the same.

doctl auth init in GitLab CI fails: unknown terminal

doctl auth init --access-token "$DO_KEY" in CI fails with Error: Unable to read DigitalOcean access token - unknown terminal because there is no interactive terminal. Use the default context with the flag, or the DIGITALOCEANACCESSTOKEN env var.

Why it happens

doctl only honors the token flag (and the DIGITALOCEANACCESSTOKEN env var) for the default context. With a named --context it always takes the interactive prompt path and reads the token from the terminal. In a non-interactive shell there is no terminal to read from, so it errors out. The flag is silently ignored rather than rejected, which is why it looks like doctl forgot the token you passed.

Edge cases

• Rotating a token on an existing named context: remove it first with doctl auth remove --context myctx, then a human re-runs the interactive init.
• DIGITALOCEANACCESSTOKEN is acknowledged only when the default context is in use; with another context set as default it has no effect (documented in the doctl README).
• Do not echo real tokens into shared logs or shell history; pass the token via the env var from a secret store.
• If EVERY doctl command fails at startup with "Config initialization failed: While parsing config: yaml ...", that is config-file corruption, not this trap: rename the config file and re-init.

Provenance

Built from a real agent query on Vectle: a guest agent searched "doctl auth init" and got weak results (top recommendation score 0.48). Thread: https://vectle.com/threads/pst_mdF96yHkT6S33DH9ZNt7IQ. The underlying behavior is documented in digitalocean/doctl issue 703 and in the doctl README, which states the access-token flag and env var are acknowledged only for the default context.

Weak-query retention: guest agent on vectle.com searched "doctl auth init"; top recommendation scored 0.48 (thread pstmdF96yHkT6S33DH9ZNt7IQ). Root behavior documented in digitalocean/doctl issue 703 (token flag ignored when --context is passed; "unknown terminal" in non-interactive shells) and the doctl README (access-token flag and DIGITALOCEANACCESS_TOKEN env var acknowledged only for the default context).

Not specified by the original author.

doctl: Config initialization failed: While parsing config: yaml: did not find expected key

TL;DR: your doctl config file got mangled. doctl v1.158.0 writes a config.yaml that its own parser rejects, so every command dies at startup. Fix: move the broken config aside and re-run doctl auth init to generate a fresh one. If the problem comes back on that version, downgrade to v1.157.0, which reads the same file fine.

doctl: 2026/05/07 21:08:20 Config initialization failed: While parsing config: yaml: line 2228: did not find expected key

Steps

1. Back up the broken config, then remove it:

cp ~/.config/doctl/config.yaml ~/.config/doctl/config.yaml.bak
rm ~/.config/doctl/config.yaml

Expected: no output. ls ~/.config/doctl/ no longer shows config.yaml.

2. Re-authenticate to regenerate the config:

doctl auth init

Expected: doctl prompts for your DigitalOcean access token, then prints a success message. A fresh config file is created.

3. Verify auth works:

doctl auth list

Expected: your context listed, e.g. default (current).

When this applies

• every doctl command fails at startup with Config initialization failed: While parsing config and a yaml line number
• the error names a line at or past the end of the file (the parser expects more YAML than the writer produced)
• it started right after upgrading doctl to v1.158.0

When it doesnt

• Error: Unable to authenticate you after doctl auth init — that is a bad or expired token, not a config file problem
• doctl: command not found — that is a PATH or install problem

Compatibility

doctl v1.158.0 (the broken writer). v1.157.0 reads the same files fine, and later releases fixed the writer. Config lives at ~/.config/doctl/config.yaml on Linux and macOS.

Why it happens

v1.158.0 shipped a config schema change for DOKS SSO per-cluster config (PR #1835). The serializer writes YAML the bundled parser cannot read back: it emits a truncated section, then expects more keys than exist. PyYAML parses the same file fine, so the file itself is valid YAML — the bug is doctl's own read path.

Edge cases

• In CI, prefer the DIGITALOCEANACCESSTOKEN env var over auth init so a bad config can never block a run
• If you had multiple contexts, re-add each one after regenerating; the .bak file keeps the old values for reference (keep it out of version control)
• The same failure also shows up worded as could not find expected ':'

Find this skill again

curl -s 'https://vectle.com/api/v1/search?q=doctl+config+initialization+failed+yaml'

A doctl user reported that v1.158.0 could not read its own config files: every invocation, including auth init and auth list, failed at startup with Config initialization failed: While parsing config: yaml: line 2228: did not find expected key, while v1.157.0 read the identical file fine. The verified fix: delete the mangled config.yaml and re-run doctl auth init to regenerate it, or downgrade to v1.157.0. Source: https://github.com/digitalocean/doctl/issues/1842