Skip to content
Documentation
Troubleshooting
Providers & Presets

Providers & Presets

Common issues with AI providers, launcher presets, and agent launches.

Codex launch fails with missing credentials

Symptom: A Codex-backed launch fails with an error telling you to run codex login or set CODEX_API_KEY / OPENAI_API_KEY.

Likely cause: The machine has neither a cached Codex login nor an API key available in the launch environment.

Fix:

codex login

# or set an API key instead
export CODEX_API_KEY="..."
# OPENAI_API_KEY also works as a fallback

Restart Valdr or your MCP host after changing credentials.

Agent launch fails with an API key error

Symptom: Launching an agent returns an error such as ANTHROPIC_API_KEY not set or a missing key for another provider.

Likely cause: The required environment variable is not set in the process that launches the session.

Fix:

# Example
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."
Valdr reads environment variables from the process that launches it or your MCP host. If you add or change a key, restart that process so it sees the new value.

Preset references a missing env var

Symptom: Preset resolution fails before the launch starts because an environment reference cannot be resolved.

Likely cause: The preset’s Env refs list names a variable that does not exist in the environment.

Fix:

  • Open Settings > Agent Presets
  • Edit the preset and review Env refs
  • Either export the missing variable or remove/update that reference

See Preset Configuration for the schema.

Model not found

Symptom: The provider returns model not found or an equivalent error.

Likely cause: The preset is using a model identifier that the selected provider does not accept.

Fix:

  • Open Settings > Providers and confirm the provider has the model you expect
  • Open Settings > Agent Presets and make sure the preset points at the right provider and model
  • If the provider changed its model catalog, update the preset to match the current model ID

Ollama preset cannot connect

Symptom: An Ollama-backed launch fails with connection refused or timeout errors.

Likely cause: Ollama is not running, or the configured baseUrl is wrong.

Fix:

# Verify Ollama is running
curl http://127.0.0.1:11434/api/tags

# If not, start it
ollama serve

Make sure the provider or preset uses the same base URL. The common local default is http://127.0.0.1:11434.

Claude Code cannot be found

Symptom: A Claude-backed launch fails because claude or claude-code is not on PATH.

Likely cause: Claude Code is not installed, or Valdr cannot find the executable from its current environment.

Fix:

command -v claude
command -v claude-code

If neither command resolves, install Claude Code or point Valdr at it with CLAUDE_CODE_EXECUTABLE.

Claude sessions keep asking for edit confirmation

Symptom: Claude-backed sessions pause repeatedly for file or tool confirmations.

Likely cause: The preset’s permissionMode is more restrictive than the workflow you intended to run.

Fix: Edit the preset in Settings > Agent Presets and adjust the Config JSON. Start with acceptEdits, default, or plan if you want confirmations in the loop. Use bypassPermissions only when you intentionally want unattended local execution and accept the broader trust boundary.

See Preset Configuration > Claude for the supported values.

Providers do not appear in launcher dropdowns

Symptom: You created a provider in Settings but it does not appear when launching agents.

Likely cause: The provider is disabled, or the preset points at a different provider type.

Fix:

  • Open Settings > Providers and confirm Enabled is Yes
  • Open Settings > Agent Presets and confirm the preset’s provider matches the provider you configured

Related

MCPSessions & Worktrees