Troubleshooting
Each heading below is an error the dg CLI prints, followed by its cause and the fix. The second half of the page covers the dg debug and dg ffprobe diagnostics.
Error messages
Your Deepgram credential has expired. Run `dg login` again.
Cause: the time-limited credential that browser login (dg login) stored has expired, and no --api-key or DEEPGRAM_API_KEY supplies another key.
Fix: run dg login. For CI, set DEEPGRAM_API_KEY, which carries no CLI-side expiry. See Authentication.
DEEPGRAM_API_KEY is not set in the configuration file
Cause: the CLI found no credential at all: no stored dg login credential, no DEEPGRAM_API_KEY, and no --api-key. Every authenticated command, including dg mcp, exits 1 with this message.
Fix: run dg login, or export DEEPGRAM_API_KEY.
Project ID is required for this command. Set DEEPGRAM_PROJECT_ID or configure via profile.
Cause: key, member, usage, billing, and request commands act on one project, and none is set.
Fix: run dg projects --set-default <project-id>, export DEEPGRAM_PROJECT_ID, or pass -p <project-id> on the command.
Warning: Project ID '<id>' not found. API key will still be stored.
Cause: dg login --api-key <key> --project-id <id> looked up the project and the API returned 404 Not Found. The CLI stores the key without the project ID and exits 0, and its summary still shows the ID you passed. Unless DEEPGRAM_PROJECT_ID or -p supplies a project, the next project command fails with Project ID is required for this command.
Fix: find the project’s ID with dg projects --list, then log in again with it: dg login --api-key YOUR_API_KEY --project-id <project-id>. Run dg whoami to confirm the stored project ID.
Warning: API key format doesn't match expected pattern
Status: fixed in CLI 0.5.0. dg login --api-key no longer checks a real key against a format pattern, and no longer needs -f to accept one. If you’re on 0.5.0 or later and dg login --api-key still stops, see the next two entries instead.
ERROR: DEEPGRAM_API_KEY is set, and logging in saves a profile that dg will use instead of it.
Cause: dg login --api-key found DEEPGRAM_API_KEY already set in your shell. Saving a profile now would shadow that variable the next time you run dg, so the command stops and exits 1 with confirmation_required.
Fix: add --yes if you want the new profile to take over: dg login --api-key YOUR_API_KEY --yes. Otherwise, drop the dg login step and keep using DEEPGRAM_API_KEY directly.
confirmation_required
Cause: dg login or dg init needs to confirm an action (saving a profile that would shadow DEEPGRAM_API_KEY, or running a template’s setup and start steps) and nothing can answer the prompt: there’s no terminal, and no -f/--yes/--install/--start. The command exits 1 instead of running the action.
Fix: pass the flag the command’s own --help names for that confirmation (--yes for dg login; --yes inside an AI-agent session, or --install/--start outside one, for dg init).
"code": "invalid_argument" from dg speak under agent mode
Cause: under a hard agent signal (see Agent-Friendly Mode), dg speak applies two guardrails that don’t apply on an interactive terminal: it refuses to read piped stdin unless the text argument is literally -, and it refuses to write audio into a pipe. Both print an error and a hint, then exit 1 with the generic "code": "invalid_argument" (there’s no separate machine-readable code for each case).
Fix: pass - explicitly to read stdin (dg speak - --out-file out.wav < text.txt), and always pass --out-file for the audio when running under CI, Claude Code, Codex, or another agent signal; don’t rely on piping audio to a player in that environment.
WARN: dg ignored <VARIABLE>: it holds a placeholder that was never filled in (${…}).
Cause: DEEPGRAM_API_KEY, DEEPGRAM_PROFILE, DEEPGRAM_PROJECT_ID, or DEEPGRAM_BASE_URL still holds an unexpanded ${...} placeholder, usually from a CI template variable that was never substituted. The CLI treats the variable as unset rather than using the literal placeholder text, and prints this warning on stderr; stdout stays clean.
Fix: fix the CI template so the variable expands, or unset it if it’s not meant to be used.
WARN: The system keyring didn't answer within 2 s, so dg didn't use the key stored there.
Cause: off a terminal, the system keyring didn’t respond within 2 seconds, so the CLI skipped it for that lookup and fell through to the next credential source (DEEPGRAM_API_KEY, then the config file).
Fix: usually nothing to do, since the CLI already fell through; if this happens often, check whether the keyring backend on that machine is slow or misconfigured.
validation errors for MemberInfo
Cause: dg members --list fails on a project member whose account has no first or last name.
Fix: list members through the API: dg api /v1/projects/<project-id>/members.
Flux STT (flux-general-en) is streaming-only and cannot transcribe a file or URL.
Cause: --model flux-general-en with a file or URL source. Flux STT runs on live audio only. The command exits 1.
Fix: stream the audio through --mic or stdin, or use nova-3 for pre-recorded audio:
Error: No such option '-o'.
Cause: -o placed after a subcommand that has no -o of its own, such as dg skills list -o json. The CLI follows the error with Hint: '-o' is a global option and must come before the subcommand and exits 1.
Fix: put -o before the subcommand: dg -o json skills list.
Refusing to delete key ... without confirmation. Pass --yes to confirm.
Cause: dg keys --delete in a non-interactive session (CI, an agent, a pipe) without --yes. The command exits 1.
Fix: add --yes after you confirm the key ID, or run --dry-run first to preview.
Missing required tools:
Cause: dg init needs git, node, npm, make, and curl on your PATH. It prints one line per missing tool and exits 1 before cloning.
Fix: install the listed tools and run dg init again.
Template not found: <slug>
Cause: the slug passed to dg init is not in the template gallery. The command exits 1.
Fix: run dg init --list to see every slug, or dg init --list --search <keyword> to filter.
Host key verification failed
Cause: during dg init, the starter’s make init clones its frontend/ and contracts/ submodules over SSH, which fails without a GitHub SSH key. dg init still prints Done! ... is ready and exits 0.
Fix: fetch the submodules over HTTPS, then run setup again:
ERROR: dg mcp supports only the stdio transport, not <value>. Nothing was started.
Cause: dg mcp --transport with a value other than stdio, most often an old config left over from before CLI 0.4.1 removed the SSE transport. --transport, --host, and -p/--port still exist as flags for compatibility with those configs, but dg mcp now runs only over stdio. The command exits 1.
Fix: remove --transport (and --host/--port, if set) from your MCP client config and let it start dg mcp with no flags. For a client that needs streamable HTTP, add the hosted docs MCP server URL directly instead of dg mcp; see MCP Server.
Please update using apt
Cause: dg update can report this for a CLI that was installed with pip as root into the system Python.
Fix: run pip install --upgrade deepctl. See Installation.
Error accessing credentials:
Cause: dg profiles --switch on a machine with no system keyring.
Fix: pass --profile <name> on each command instead.
Diagnose with dg debug
dg debug audio
Analyzes a file’s or URL’s compatibility with Deepgram using ffprobe and suggests encoding settings.
dg debug network
Tests connectivity to Deepgram and reports the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY settings it sees.
--timeout defaults to 10 seconds, and --endpoint defaults to api.deepgram.com. dg debug network’s probe requests never carry stored Deepgram credentials: the throwaway HTTP client it builds for each test has no auth configured and doesn’t read ~/.netrc, so there’s nothing for a ~/.netrc entry to attach even if one exists for your Deepgram host.
dg debug browser
Starts a local debug server that checks a browser’s compatibility with Deepgram services.
The port is auto-selected starting from 3000, and the session waits 60 seconds for a browser by default.
dg debug probe
Runs a local WebSocket proxy that forwards streaming audio to Deepgram and runs ffprobe on it at intervals. Point your app at ws://localhost:<port>/v1/listen in place of wss://api.deepgram.com/v1/listen.
The proxy picks a port from 3100 to 3199 and probes every 131,072 bytes of audio or every 10 seconds.
dg ffprobe
dg ffprobe shows which ffprobe binary the CLI uses for audio analysis. --path sets a custom binary, stored as tools.ffprobe_path, and --reset returns to auto-detection.
Get more help
Paste the error and this page into your coding agent. For anything this page does not cover, see Support or open an issue on the CLI issue tracker.