Troubleshooting

Troubleshooting

Errors in the order you are likely to meet them. Each was seen during the 2026-10-16 verification runs.

Message	Cause	Fix
requires tool 'agent' which is not supported by local runtime	noetl binary predates kind: agent	Upgrade to noetl 5.1.0 or newer (Tutorial §1).
agent step needs an auth: block / agent requires an auth: block	framework: claude without auth:	Add auth: {type: api_key, credential: anthropic}.
credential alias 'anthropic' is not set or empty; local mode reads it from $NOETL_CREDENTIAL_ANTHROPIC	variable unset, empty, or the key file is missing ($(cat missing) is empty)	Create ~/.config/noetl/anthropic.key; set the variable in the same command or shell as noetl run. Commands in separate terminals don't share exports.
Anthropic API returned 401: invalid x-api-key	the value isn't an API key	Check: head -c 7 ~/.config/noetl/anthropic.key must be sk-ant-. A pasted export …= line, quotes, or another secret all fail here.
Anthropic API returned 400: Your credit balance is too low …	valid key, no prepaid credits	Console → Settings → Billing. A Pro/Max subscription does not cover API calls; use framework: claude-code to run on it instead.
Anthropic API returned 404 … mentioning the model	model id not available to your account	Change model: (or --set model=… in the showcase playbooks).
agent output hit max_tokens=N on turn T before finishing (content blocks: [thinking])	the model spent the output budget on reasoning (adaptive thinking)	Add thinking: disabled, or raise max_tokens.
… (content blocks: [text]) / [tool_use]	the answer or tool calls didn't fit in max_tokens	Raise max_tokens, or ask for a shorter report.
agent did not finish within max_turns=N	the model kept calling tools	Raise max_turns a little, or make tool output more decisive / smaller. Run with --verbose to see each tool call.
cannot start 'claude' (…); install the Claude Code CLI or set claude_bin	CLI not on PATH (common under systemd)	curl -fsSL https://claude.ai/install.sh | bash, then --set claude_bin=$HOME/.local/bin/claude or fix the unit's PATH.
claude-code run failed: Failed to authenticate: OAuth session expired …	the CLI's sign-in lapsed	Run ~/.local/bin/claude interactively and sign in again.
framework claude-code uses the claude CLI's own sign-in; remove auth:	auth: on a claude-code step	Delete auth:.
framework claude-code runs its own tools; use allowed_tools / mcp_config	tools: on a claude-code step	Use framework: claude for NoETL-run tools, or grant Claude Code tools with allowed_tools.
credential file … is readable by others (mode 644); run: chmod 600 …	a credential file with loose permissions	Run the printed chmod 600.
google token refresh for 'gmail-x' failed with 400: invalid_grant — …	refresh token revoked, or expired (7 days while the OAuth app is in Testing)	Re-run noetl credential google gmail-x --client-secret-file …; to stop weekly expiry see Connect Gmail § 1.
Google returned no refresh_token …	Google had already granted this client offline access	Remove the app at myaccount.google.com/permissions and run noetl credential google again.
access_denied / "app is blocked" on the consent screen	the account isn't a test user while the app is in Testing	Add it under Google Auth Platform → Audience → Test users.
Gmail tool returns {"status": 403, …} mentioning the Gmail API	Gmail API not enabled in the OAuth client's project	APIs & Services → Library → Gmail API → Enable.
Execution timed out	claude-code run exceeded timeout (300 s default)	Raise the step timeout, or give the prompt less to do.

Seeing what happened

• --verbose prints 🤖 Agent: …, each 🔧 Agent tool <name> → <playbook>, and Agent finished after N turn(s).
• --json prints the run envelope; the agent's result is in final_result / step_results.<step>.
• Under systemd: journalctl --user -u inbox-triage.service.