Skip to content

Troubleshooting

Common problems and how to resolve them. If a quick check helps first, confirm your model is reachable with a single-shot call:

gdc chat "say hello"

If that returns a reply, your provider settings are correct and the problem is elsewhere.

Can't reach the model / connection errors

  • Is the backend running? Start your local runner (for example ollama serve) and confirm it's listening on the expected port.
  • Is the endpoint right? Check base_url in your config, or the --base-url flag. Local defaults: Ollama http://localhost:11434/v1, llama.cpp http://localhost:8000/v1, LM Studio http://localhost:1234/v1.
  • Is the model name right? It must match a model the backend has loaded or pulled.

→ Model providers

Empty responses from local models

Some local models occasionally return an empty reply right after using a tool. If you hit this, add --repair-empty-turn to a headless run — gdc recovers and re-prompts instead of stopping:

gdc print --repair-empty-turn "..."

The iteration cap still applies, so a stuck model ends the run rather than looping forever.

The agent stops before finishing a task

A run is capped at a number of tool-using rounds (16 by default). For a larger task, raise it:

gdc print --max-iterations 40 "..."

The run also stops if the model repeats the same tool call several times — usually a sign it's stuck. Rephrasing the request often helps.

An action was denied unexpectedly

gdc denies actions when it's uncertain, and headless runs deny anything that would need approval unless you opt in:

  • In the terminal app, answer the approval prompt (A to allow).
  • For a headless run that needs to act, add --auto-approve (trusted environments only).
  • Check your permission rules for a deny that matches — deny always wins.

→ Permissions

Configuration changes have no effect

  • Precedence. A project's .gdc/config.toml overrides your user config; environment variables and command-line flags override both. See Configuration overview.
  • Typos. Unknown keys are reported — check the startup output for a warning.
  • Wrong file. Confirm which file you edited; gdc --config <path> forces a specific one.

The terminal app looks wrong or the mouse misbehaves

  • Press Ctrl+L to force a full redraw.
  • If text selection is awkward with the mouse, disable mouse capture: GDC_DISABLE_MOUSE=1 gdc-tui.
  • Switch theme with /theme dark or /theme light if contrast is poor.

I can't connect the app to a server

  • Confirm the server is running and its bind address (gdc serve --bind ...).
  • Connect with a matching address: gdc-tui --bind <host:port>.
  • If the server uses TLS, make sure the client trusts its certificate — for a self-signed certificate, pin it. See TLS.

Sessions or history seem missing

gdc sessions list is scoped to the current project by default. Widen the search:

gdc sessions list --all          # every project
gdc sessions list --cwd /path    # a specific project

Getting more detail

Raise logging verbosity to see what's happening:

RUST_LOG=debug gdc print "..."

For the terminal app, write logs to a file with --log-dir <dir> (they're off by default).