Troubleshooting¶

Can't reach the model / connection errors¶

gdc chat "say hello"

Check	Action
Backend	Confirm the server is running
Endpoint	Check `base_url`, including `/v1`
Model	Match the name exposed by the backend
Credential	Supply the endpoint's API key when required

A chat reply verifies connectivity; tool execution requires a model supporting native tool calls.

Empty responses from local models¶

gdc print --repair-empty-turn "<task>"

Re-prompts after an empty turn. The iteration limit still applies.

The agent stops before finishing a task¶

Cause	Action
Iteration limit	Set `--max-iterations N` for a larger task
Repeated identical tool call	Inspect the failed operation or revise the request
Timeout	Check the backend or adjust `--timeout-secs N`

An action was denied unexpectedly¶

Cause	Action
Interactive approval	Answer the prompt
Headless ask	Use `--auto-approve` when unattended approval is intended
Deny rule	Review matching permission/profile rules
Extension trust	Review MCP or plugin trust settings

Configuration changes have no effect¶

Check CLI/environment overrides, active provider selection and project config. An explicit --config PATH loads one file. Missing or invalid explicit files fail; automatically discovered invalid files are warned and skipped.

The terminal app looks wrong or the mouse misbehaves¶

Symptom	Action
Stale screen	`Ctrl+L`
Mouse selection	`GDC_DISABLE_MOUSE=1 gdc-tui`
Poor contrast	`/theme dark` or `/theme light`
Missing newline	Check terminal support for `Shift+Enter`

I can't connect the app to a server¶

Check the listen address and use a matching gdc-tui --bind URL. Non-loopback server binds require a swarm role and TLS. The TUI has no swarm certificate-pin flag; use a trusted TLS endpoint or loopback tunnel. See TLS.

Sessions or history seem missing¶

gdc sessions list --all
gdc sessions list --all-projects
gdc --db-path ~/.gdc/projects/<slug>/sessions.db sessions show <id>

--all searches one database; --all-projects scans local TUI databases.

Getting more detail¶

RUST_LOG=debug gdc print "<task>"
gdc-tui --log-dir /path/to/logs

The TUI writes gdc-tui.log; file logging is disabled by default.