Skip to content
Documentation
Troubleshooting
Providers & Presets

Providers & Presets

Common issues with AI providers, provider 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-..."
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.

For OpenCode, check native authentication and provider configuration for the OS user running Valdr. When storing a credential override in a Valdr preset, use an environment reference such as {"envRef":"MY_MODEL_KEY"}.

Old provider preset no longer launches after 0.3.4

Symptom: A preset using gemini, openai, or anthropic fails to launch.

Fix: Create an enabled OpenCode provider with an empty model list, then create replacement presets with the desired model in Config JSON. Update affected agents and workflow selections to the new presets. Existing presets are not automatically converted. Claude, Codex, and Ollama remain supported.

OpenCode cannot start or requests interactive input

Fix: Check the OpenCode setup requirements. Start with config: {} to use your native configuration, then add selectors supported by your setup. An explicit model must use provider/model.

Interactive permission or question requests fail in headless sessions. Configure suitable permissions in OpenCode or the preset, and make project configuration available in the session’s execution directory or worktree. See OpenCode configuration.

Reasoning effort rejected at launch

Fix: Use low, medium, high, xhigh, or max for Claude. Codex also accepts ultra and legacy minimal. Choose Use preset/default to inherit the provider’s setting. OpenCode uses variant instead. Availability depends on the selected model and runtime; invalid effort values now produce a clear launch error.

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 > Agent Presets and make sure the preset points at the right provider and model
  • For OpenCode, check config.model uses provider/model and that the model is available to your OpenCode account. The Valdr provider’s model list can stay empty
  • For other providers, check any model choices you use in Settings > Providers
  • If the provider changed its model catalog, update the preset to match the current model ID

Adding a model to Valdr’s optional dropdown list does not grant access to that model.

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. Choose acceptEdits when you want file edits and supported filesystem operations approved automatically. Use default for standard permission checks, or plan for exploration and planning without automatic edit approvals. 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 when starting a session

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