SCREENERBOTDocs
DocsLLM & AnalysisTroubleshooting
LLM / ASSISTANT / AGENTS

Diagnose the owner that failed

Provider transport, model-scored analysis, Assistant chat, Agent Control, and the MCP adapter are separate. Start at the boundary named by the error instead of treating every model-backed feature as one module.

First five checks

Establish the active path

  1. 01Confirm [llm] enabled = true.
  2. 02Confirm llm.default_provider names one of the nine supported providers.
  3. 03Confirm that exact [llm.providers.<name>] entry is enabled and has a current model ID and credential.
  4. 04Confirm the consumer is enabled: [llm_analysis] for scoring or [assistant] for chat/schedules.
  5. 05Read the Events page for the provider, parse, timeout, or permission error that actually occurred.

Provider does not answer

Disabled or unconfigured

  • Check the exact selected provider, not merely whether some provider is configured.
  • For API providers, confirm the key is present. Status responses intentionally expose only has_api_key.
  • For Ollama, confirm the local service is running at the configured base_url and the model is already pulled.
  • Use a current model ID from the provider's own model list; the docs do not pin versioned IDs.

Timeout or rate limit

  • Match rate_limit_per_minuteto the selected provider's current plan.
  • Reduce analysis volume or enable filtering cache where repeated token evaluations are expected.
  • For local models, use a model that fits available memory and hardware.
  • Check the provider status page when requests that previously worked begin failing.

Provider changes require a restart

The provider manager is initialized once per process. Changes to credentials, enabled providers, model IDs, or llm.default_provider are persisted but require a ScreenerBot restart before provider clients are rebuilt. Analysis settings are separate and can be updated live.

Filtering behaves unexpectedly

Never reaches the model

LLM analysis is the final filtering stage. A token rejected by meta, on-chain, DexScreener, GeckoTerminal, or RugCheck is correctly discarded before any provider call.

Low confidence

Confidence below min_confidence follows fallback_pass. There is no advisory mode orUNCERTAIN pipeline state.

Provider failure

A timeout, malformed response, or unavailable provider also follows fallback_pass. ScreenerBot does not automatically try a second configured provider.

Use integer confidence values

min_confidence and auto_blacklist_min_confidence are 0–100 integer percentages. Values such as 0.8 belong to the retired configuration and are invalid here.

Assistant tools or confirmations fail

Check [agent_control]

The in-app Assistant and scheduled tasks use the five category values under [agent_control]. deny blocks a category;ask_user queues approval; allow permits it. The interactive Assistant still confirms tools whose definitions are mutating.

Keep the session attached

Confirmation responses are bound to the conversation session. If an approval appears stale, return to the same session and use the current pending action rather than creating a duplicate request.

Agent Connection cannot list tools

Terminal
SCREENERBOT_CLIENT_ID=<id> \
SCREENERBOT_PAIRING_SECRET=<secret> \
screenerbot mcp doctor
Exit 3: No validated live runtime was found.
Exit 4: Client ID or pairing secret is missing.
Exit 5: Runtime exists but its loopback bridge is unreachable.
Exit 6: Pairing is invalid/revoked, or Agent Control is disabled.

A paired connection uses its own live per-category policy, not the five in-app values in [agent_control]. Change it under Settings → Agent Connections.