Troubleshooting
Find your symptom in this page. For configuration or startup failures, run
jazz config validate first. Use jazz config show to inspect resolved settings
and --debug to collect details from a failing command.
jazz config validate # names every setting Jazz rejects, and suggests the one you meant
jazz config show # the configuration Jazz actually resolved
jazz config resolved # the same, with the layer that set each value and any value ignored
jazz --debug <command> # the same command, logging at debug level
Where the logs are
Everything is under ~/.jazz/logs (or $JAZZ_HOME/logs, or $JAZZ_LOG_DIR when set).
| File | Holds |
|---|---|
jazz.log |
Everything not tied to one conversation |
<conversation-id>.log |
One conversation or run: model requests, tool calls, errors |
<workflow>.log, <workflow>.error.log |
Output of a scheduled workflow |
reminder-<id>.log, wake-trigger-<id>.log |
Output of a one-shot reminder or wake-up |
Set logging.level to debug in ~/.jazz/config.json to keep debug logging on, and
logging.format to json for one object per line. --verbose only adds detail to
jazz agent list; it does not change what is logged.
Crash reports
When a Jazz process dies of an uncaught exception or an unhandled rejection (the daemon, a chat
bot, jazz run, the chat), it writes a report to logs/crashes/ before it exits with code 1:
~/.jazz/logs/crashes/crash-2026-11-05T09-14-02-117Z-telegram-bot-48211.log
The name carries the time, the role (daemon, run, chat, cli, or a bot such as
telegram-bot) and the process id. The file is plain text: the role, version, platform, runtime,
uptime, the error and its stack, and the last 100 lines the process wrote to stderr. Secret values
are replaced by placeholders, but read it before you attach it to an issue. Only the 20 newest
reports are kept.
On a crash the process also stops what it was serving first: a bot stops taking messages and
cancels its running turns, the daemon releases its lock and port, and the fullscreen interface
restores the terminal. Release steps get 3 seconds in total. The same error and the report path
are printed on stderr. When a bot’s per-conversation jazz run crashes, the bot logs the report
path server-side; the chat only sees the usual failure message.
The provider rejects the key
The message names the provider, for example “OpenAI API key is missing or invalid”.
- Check the agent uses the provider you think it does:
jazz agent show <agent>. - Save the key again without putting it in your shell history.
jazz config set openaiprompts for it; replaceopenaiwith your provider. - Or supply the provider’s environment variable, such as
OPENAI_API_KEY. It takes precedence over the saved key; update or unset a stale variable before saving a new key. See Environment variables. - Jazz trims surrounding whitespace when saving a key. If it is still rejected, check that you copied the complete key for the correct provider.
A local model never answers
The run waits, then fails with “Provider stream produced no first part for 120s and was abandoned”.
- Check the server from the machine Jazz runs on, not from your laptop when Jazz runs
elsewhere:
curl http://127.0.0.1:11434/api/tagsfor Ollama,curl http://127.0.0.1:8080/v1/modelsfor llama.cpp. - Check the address Jazz uses. A saved
llm.ollama.base_url(orllamacpp,vllm,sglang) wins overOLLAMA_BASE_URLand the other variables. Change it under Settings → LLM Providers in thejazzhome menu. Connection failures name the resolved server address used by the request, including in retry notices. - A large model loading from disk can take longer than two minutes before its first
word. Raise
llm.streamIdleTimeoutMs(orJAZZ_STREAM_IDLE_TIMEOUT_MS), and setllm.ollama.keep_aliveto30mor-1so Ollama keeps the model loaded between runs. - “No models found” means Ollama has nothing pulled: run
ollama pull <model>. - “The server … rejected the request (401)” means the server was started with an API key:
set
llm.<provider>.api_key, or runjazz agent createagain, which asks for it.
Local and air-gapped models covers setup, and Diagnose provider failures covers tool-call problems on llama.cpp, vLLM and SGLang.
The answer is empty
Jazz warns “model returned an empty response” when the model sent no text, no reasoning and no tool call.
- A local model with too small a context window often stops answering once the conversation
grows. Set
llm.numCtxon the agent to a value the server can hold, or start a new conversation. - A provider’s safety filter can end an answer with nothing in it. The conversation log records how the request finished.
- Try the same prompt with another model to tell a model problem from a Jazz one.
The agent has no tools
Jazz sends tools only to models it knows can call them. A model the catalog does not list, such as one released this week, gets none, and the log says “Tools skipped because model does not support tools”.
- If the model does call tools, declare it:
jazz config set 'llm.capabilityOverrides.<provider>."<model-id>".supportsTools' true. See Model capability overrides. - With
JAZZ_OFFLINEset and no cached catalog, no cloud model is known. Run Jazz once online, or see Model catalog options. - A persona or
deniedToolsmay leave a tool out on purpose./toolsin a chat lists what the agent actually has.
Secrets will not save
Jazz stores secrets in macOS Keychain or, on Linux, the Secret Service (secret-tool). A
Linux machine without a desktop session usually has no Secret Service; Jazz then uses
~/.jazz/secrets.json, readable only by you.
- If
$JAZZ_DISABLE_KEYRINGprevents storage, unset it or supply the secret as an environment variable.
The daemon is not running
Goals, loops and in-process schedules need jazz daemon. Check that it answers:
curl http://127.0.0.1:4747/health # {"ok":true,...} when it is up
- Started by hand, it runs in the background and prints nothing. Run
jazz daemon --foregroundto watch it, andjazz daemon stopto stop it. - Installed as a service with
jazz daemon install, it logs to the system:journalctl -u jazz-daemon -n 50 --no-pageron Linux,log show --predicate 'process == "jazz"' --last 5mon macOS. - A different port needs
--porton every command that talks to it.
See Daemon.
A scheduled workflow did not run
jazz workflow scheduled # is it scheduled at all?
jazz workflow history <name> # did it start?
Then read ~/.jazz/logs/<workflow>.log and <workflow>.error.log. A workflow scheduled
with launchd runs missed sleep slots once on wake; cron skips them. The next interactive
jazz offers to catch up on missed runs. With scheduler.mode set to in-process, nothing runs unless
the daemon is up. See Scheduled runs.
Reporting a bug
Open an issue with jazz --version, your operating
system, the output of jazz config validate, and the relevant lines from the conversation’s
log. Remove keys and personal content first: logs can contain both.