Troubleshooting

Common issues and their solutions.

Plugin issues

"Missing config" — plugin allows everything

The plugin can't find ~/.veto/config.json. Run the setup command:

/veto:setup

This will create the config file with your API key and fail policy.

Plugin not intercepting tool calls

Check that the plugin is installed:

/veto:status

If it reports "not connected", reinstall:

Linux / macOS:

/plugin marketplace add damhau/veto-linux
/plugin install veto-linux

Windows:

/plugin marketplace add damhau/veto-windows
/plugin install veto-windows

Connection timeout

The default timeout is 25 seconds. If your server is slow or remote, edit ~/.veto/config.json and increase it:

{
  "server_url": "https://api.vetoapp.io",
  "api_key": "YOUR_API_KEY",
  "fail_policy": "open",
  "timeout": 30
}

Debug logging

The plugin logs to ~/.veto/hook.log. Check it for errors:

tail -f ~/.veto/hook.log

LLM Proxy issues

ECONNRESET or Claude Code freezes

This happens when the guardrail buffers tool calls for evaluation and no data flows to the client for too long. The guardrail sends keepalive pings every 5 seconds to prevent this.

If you still see this:

  • Check that your Veto server is responding within the timeout
  • Check the LiteLLM logs: docker-compose logs litellm
  • The guardrail logs detailed timing info for every evaluation

"[BLOCKED BY POLICY]" message

This means a tool call was denied by a rule or AI scoring. Check the audit log in the dashboard to see which rule matched and why.

Tool calls are not being evaluated

Check that the LLM Proxy is properly configured:

  • Verify the proxy is enabled in Settings → LLM Proxy in the dashboard
  • Verify your proxy key is valid (try regenerating it from the dashboard)
  • Check that ANTHROPIC_BASE_URL points to the proxy (https://proxy.vetoapp.io for hosted, or your self-hosted URL)
  • Check the server logs for errors: docker-compose logs server

Guardrail raises exception but Claude ignores it

If GuardrailRaisedException is raised but Claude Code silently drops it, make sure you're running the latest version of the guardrail script. An earlier version had a bug where the exception escaped the keepalive loop.

Dashboard issues

Can't log in

  • Verify your email and password
  • Check that the API server is running: curl https://api.vetoapp.io/health
  • If self-hosted, check the server logs: docker-compose logs server

Rules not taking effect

  • Rules are cached briefly. Changes should take effect within a few seconds.
  • Check that the rule is enabled (not disabled)
  • Check rule priority — a lower-priority rule might be matching first
  • Use the Simulate feature in the dashboard to test rules without running Claude Code

Audit log is empty

  • Verify that tool calls are going through the Veto server (check the plugin or proxy logs)
  • Check that your API key is valid and associated with the correct org

Self-hosted issues

Database migrations fail

Run migrations manually:

cd server && uv run alembic upgrade head

If a migration fails halfway, check for duplicate enum types. Veto uses idempotent enum creation:

DO $$ BEGIN CREATE TYPE myenum AS ENUM ('a', 'b');
EXCEPTION WHEN duplicate_object THEN null; END $$;

Redis connection refused

Ensure Redis is running and accessible at the configured URL:

redis-cli -u redis://localhost:6379/0 ping

LLM Proxy can't connect to Veto server

Check the server logs for connection errors: docker-compose logs server

For self-hosted deployments, ensure the LiteLLM service can reach the Veto server container. In Kubernetes, services communicate via internal DNS — verify the service name matches your deployment configuration.

Getting help

If you need assistance:

  • Check the documentation for guides and examples
  • Contact support at support@vetoapp.io
  • Include your integration mode (hook or proxy), relevant log output, and steps to reproduce