Troubleshooting

The Config File Changed But The Bot Did Not

If the Athena dashboard is enabled, config can be stored in MongoDB. In that case, editing configuration/aio_agent.json5 may not affect the live bot.

Use the dashboard to save settings, or update the dashboard-backed config data and restart AthenaBot.

Welcome Messages Are Still In English

In v1.4.2, open AIO Agent > Member Events and enable AI Personalize Welcome. For Dutch, set AI Welcome Language to Dutch and AI Welcome Prefix to Welkom bij {{server_name}}!, then save. The AI language controls the generated sentence only; the prefix must be translated separately.

Before v1.4.2, AI welcomes used a hardcoded English prefix. A personality instruction cannot translate that prefix. Update the full plugin to get the new fields in both dashboards. Restart AthenaBot and the dashboard process, then refresh the page if the fields are missing.

For a fixed message, disable AI Personalize Welcome and translate Welcome Message. If the AI provider fails, personalized welcomes send only the prefix. Changing Date/Time Locale does not change the welcome language.

Approved History Commands Fail Or A Private Reply Cannot Be Delivered

Update to v1.4.2 if approving /history produces Cannot read properties of null (reading 'id'). AIO now resolves Discord user and other command options before running Athena commands.

Private command replies need an approval interaction from the original requester. The requester must approve personally. If someone else approves, confirmation is disabled, or the interaction is unavailable, run the native slash command directly. AIO will not post a private reply publicly as a fallback.

A reply delivery failure does not prove that the command made no changes. Check the result before repeating an action that changes server state.

Anthropic Rejects The Temperature Parameter

If the provider reports temperature is deprecated for this model, update to v1.4.2. AIO omits the parameter for recognized affected models and retries once without it when an unrecognized model returns that specific error. Changing the temperature to zero does not remove the parameter.

npm Warns That Install Scripts Were Blocked

AIO uses @google/genai for Gemini; that package depends on protobufjs. An up to date message followed by blocked-script warnings does not by itself mean the update failed.

For the reported versions, @google/[email protected] declares a preinstall command that only prints preinstall: no-op. The [email protected] postinstall script checks dependency version conventions and can print a warning; it does not build or download runtime files. These two scripts are not required for AIO to work. This applies to those scripts, not every package’s install steps.

An Addon Did Not Load

Check:

• The addon folder is under plugins/aio_agent/data/addons/.
• addon.json exists and is valid JSON.
• enabled is not false in addon.json or config.json5.
• The configured entry file exists.
• Console logs for aio_agent:addons.

Run /aio reload after changing addon config, prompt files, or knowledge text. Required addon failures stop AIO Agent from loading; optional addon failures are logged and AIO continues.

A Dashboard Field Will Not Accept My Value

Current AIO Agent dashboard builds treat customer-specific values as free text: model names, docs URLs, knowledgebase folders, prompt files, timezones, locales, API base URLs, and forum header templates should accept arbitrary values.

If a field still behaves like a locked dropdown:

• Confirm the dashboard is running the current AIO Agent build.
• Hard-refresh the browser.
• Restart the dashboard process.
• Check whether you are editing the core configuration page or the custom AIO addon page. Both should expose the same free-text fields.

The Bot Says The API Key Is Missing

Check:

• llm_api_key is filled in, or the correct environment variable is set.
• llm_provider matches the key type.
• For custom, llm_api_base_url is set.
• AthenaBot was restarted after environment changes.

Environment variables:

AIO_AGENT_LLM_API_KEY=...
AIO_AGENT_GEMINI_API_KEY=...
AIO_AGENT_OPENAI_API_KEY=...
AIO_AGENT_ANTHROPIC_API_KEY=...
AIO_AGENT_OPENROUTER_API_KEY=...

The Separate Reasoning Key Is Not Being Used

Check:

• reasoning_llm.enabled is true.
• The relevant use_for_* switch is enabled.
• reasoning_llm.api_key or AIO_AGENT_REASONING_API_KEY is set.
• The reasoning provider/model combination accepts the requested tools or embeddings.

Blank reasoning fields intentionally inherit the primary provider, model, base URL, and eventually the primary key.

Prompt Caching Shows No Cache Hits

Caching is controlled by the provider and model. AIO can send supported cache controls, but it cannot guarantee a hit.

Check:

• prompt_caching.enabled is true when using AIO-managed controls.
• The provider/model supports the selected automatic or explicit mode.
• Repeated requests share a sufficiently long, identical prompt prefix.
• Explicit OpenAI mode uses GPT-5.6 or later.
• Explicit Gemini prompts meet the provider’s minimum cache size.

The first request normally creates or writes cache content; later matching requests can report cached input. If a provider rejects explicit caching, AIO falls back safely instead of failing the response.

Provider Overload Or 503 Errors

Temporary provider failures can happen when a model is under heavy demand. AIO Agent retries transient 429, 500, 502, 503, and 504-style errors according to llm_retry_attempts and llm_retry_base_delay_ms.

If errors continue:

• Try a different model.
• Lower llm_max_output_tokens.
• Reduce chat/ticket usage.
• Increase cooldowns.
• Use FAQ entries for common fixed answers.

The Bot Mentions Internal Files Instead Of Links

Set docs_url to the public documentation URL. The prompt and direct docs-answer path use this value when users ask for documentation.

The Knowledgebase Seems Out Of Date

Run:

/aio reload

Then restart AthenaBot if you changed config paths, recursive loading, channel permissions, or environment variables.

remember this Does Not Save Anything

Memory is approval-gated. A request creates a proposal; it does not write to the knowledgebase until an authorized reviewer approves it.

Check:

• self_improvement.enabled is true.
• self_improvement.review_channel_id points to a private text channel the bot can view and post in.
• The requester meets minimum_requester_tier.
• Reviewers are AIO owner/admin users or match the configured approver users or roles.
• memory_file is a relative .md or .txt path inside the AIO knowledgebase.

For automatic proposals, also enable auto_detect and verify source_scope, selected channels/categories, exclusions, cooldown, confidence, and hourly limit. Approved entries are loaded immediately; rejected or expired proposals are not written.

The Knowledgebase Costs Too Much

Use knowledgebase_mode: "search" instead of full. Search mode stores the loaded docs in memory, then sends only matched chunks for the current request.

Recommended defaults:

knowledgebase_mode: "search",
knowledgebase_search_top_k: 6,
knowledgebase_search_max_chars: 12000,
knowledgebase_embeddings_enabled: false

For very large docs, try hybrid retrieval:

knowledgebase_mode: "hybrid",
knowledgebase_embeddings_enabled: true,
knowledgebase_embedding_provider: "llm"

If the AI misses important policy or pricing pages, add a stable substring to knowledgebase_always_include_sources.

Embeddings Are Not Working

Check:

• knowledgebase_embeddings_enabled is true.
• knowledgebase_mode is search or hybrid.
• The embedding provider has an API key.
• Custom or OpenAI-compatible providers have a valid knowledgebase_embedding_api_base_url.
• The embedding model exists for that provider.

If embedding calls fail, AIO Agent falls back to local search. Local search is still usable and is the recommended default for most customers.

Tool Calls Use Fake IDs

The tool executor validates Discord IDs before execution. If the model invents a placeholder such as 12345, the tool call is rejected. For current-channel tools such as delete_messages, read_channel_messages, and close_ticket, the plugin can use the current channel when the model omits channel_id.

Channel Permission Editing Or Deletion Fails

Check the requester tier and confirmation first. set_channel_permissions requires Admin, while delete_channel is owner-only and always destructive. The bot also needs Manage Channels and must be above any affected roles.

AIO intentionally refuses to delete:

• active ticket channels
• Discord system channels
• channels referenced by AIO review, audit, alert, memory, or log settings

Change the referencing configuration first, save it, and retry with the exact channel ID. Only the supported permission names can be allowed, denied, or reset to inherited state.

Delete Messages Deletes The Wrong Messages

Current builds count messages before the user’s delete request. The request message, AI confirmations, AI status messages, and AIO workflow embeds are not counted toward the requested number.

If behavior still looks wrong:

• Make sure delete_messages is in require_confirmation_for while testing.
• Ask from the owner account because delete_messages is owner-only.
• Confirm the bot has Manage Messages.
• Remember Discord bulk delete cannot remove messages older than Discord’s bulk delete limit.

Ticket Close Says The AI Cannot Close Tickets

Check:

• tickets.enabled is true.
• The tickets plugin is installed and loaded.
• tickets.allow_ai_ticket_close is true.
• The requester meets tickets.ticket_close_minimum_tier, or tickets.ticket_close_allow_creator is true for ticket creators.
• The channel is an active ticket.

For creator close requests with confirmation, use:

tickets: {
  allow_ai_ticket_close: true,
  ticket_close_requires_confirmation: true,
  ticket_close_allow_creator: true
}

That uses Athena’s native close-request buttons instead of the generic AIO Confirm Action embed.

A Timed-Out Close Request Closed After Someone Said Ok

That should not happen on current builds. Plain text does not approve expired confirmations. Only a fresh explicit close intent or a valid native button approval can close a ticket.

Update AIO Agent and test again with:

1. Customer sends close ticket.
2. Let the close request time out.
3. Customer sends ok.
4. Confirm the ticket stays open.
5. Customer sends close ticket again or clicks a fresh button.

The Agent Repeats Its Previous Reply

Current builds filter workflow embeds and strip automatic bot mention prefixes from Discord replies before sending history to the model. They also remove a duplicated previous bot answer if the model starts its next response with it.

If repetition still happens:

• Lower max_context_messages.
• Check whether a custom prompt tells the model to quote prior answers.
• Remove large copied transcripts from recent chat history.

Moderation Is Too Aggressive

• Start with moderation.mode: "ask".
• Lower moderation.sensitivity.
• Increase moderation.min_confidence.
• Disable kick and ban until reviewed.
• Add staff to immune_users or immune_roles.
• Tighten server_rules so the model has clear criteria.

A Warning Is Missing From AIO Or Cannot Be Removed

AIO 1.4.0 does not keep a separate warning database. Warnings, timeouts, kicks, bans, reversals, punishment history, notifications, thresholds, and moderation logs all go through Athena’s moderation plugin.

• Make sure Athena’s moderation plugin is installed and enabled.
• Use /history or /aio modlog to find the Athena punishment ID.
• Run /aio remove-warning user:<user> warning-id:<id> reason:<reason>.
• Omit warning-id only when you intend to remove the latest active warning.
• Confirm the bot and requester meet Athena’s normal moderation permissions.

/aio reputation remains only as a legacy alias for Athena’s history; AIO no longer calculates its own reputation score.

The Agent Replies To Normal Conversations

Check chat.response_mode. Use "smart" to answer help and questions without replying to every watched-channel message. "always" intentionally responds to every eligible message.

Also check:

• chat.channels includes only channels AIO should watch.
• chat.wake_words does not contain a common word or phrase.
• chat.respond_to_name is false if typing the bot name should not wake Smart.
• FAQ triggers are not so broad that they match normal conversation.

For strict ping-only behavior, use chat.response_mode: "mentions". That mode accepts only a real mention or a Discord reply to the bot.

Smart Mode Ignores A Question

Smart fails closed when a message is unclear, the classifier is disabled, the provider errors, confidence is below the threshold, or the user reaches the hourly classifier-check cap.

Check:

• chat.response_mode or tickets.response_mode is "smart".
• response_gate.use_llm_classifier is true for ambiguous questions.
• response_gate.classifier_model is a valid model name, or leave it empty to use the main model.
• response_gate.confidence_threshold is not set unnecessarily high.
• response_gate.max_checks_per_user_per_hour has not been reached.
• The question is within chat.allowed_topics.

Mention the bot, reply directly to one of its messages, or—when chat.respond_to_name is enabled—call it by its username, server nickname, or a configured chat.wake_words alias when an answer is required immediately.

Smart Mode Uses More Tokens Than Expected

Smart does not classify ordinary conversation, clear help requests, FAQ matches, direct mentions, or intentional bot-name calls. Only ambiguous messages use the response gate.

To reduce classifier usage further:

• Set response_gate.classifier_model to a compatible lower-cost model.
• Lower response_gate.context_messages.
• Lower response_gate.max_output_tokens.
• Lower response_gate.max_checks_per_user_per_hour.
• Add common fixed questions to faq.entries.
• Set response_gate.use_llm_classifier to false if uncertain messages should always be ignored.

Classifier calls appear in /aio usage with normal LLM usage.

The Agent Does Not Respond In Tickets

Check:

• tickets.enabled is true.
• tickets.response_mode is not mentions unless the customer is mentioning or replying to the bot.
• mode is general or support.
• The tickets plugin is installed and loaded.
• Use /aio handle to start the agent manually if tickets.auto_activate is false.
• If testing automatic activation, the ticket category must be included in tickets.auto_activate_categories, or the list must be empty.
• If the server uses a third-party ticket bot, enable tickets.external_ticket_fallback.enabled and configure channel/form markers.
• The channel is not cooling down.
• The user did not use a human handoff phrase.
• In Smart mode, another human was not the most recent active speaker. Mention the bot directly if staff wants it to rejoin the ticket.

Third-Party Ticket Bot Channels Fall Back To Chat

If AIO replies like a normal chatbot instead of running strict ticket workflow, AthenaBot may not be able to resolve the channel as a native ticket.

Enable external fallback:

tickets: {
  external_ticket_fallback: {
    enabled: true,
    require_bot_mention: true,
    channel_name_patterns: ["ticket", "order"],
    form_text_contains: [
      "Your order ticket has been created",
      "Question 1",
      "Powered by tickets.bot"
    ]
  }
}

Then restart AthenaBot and test in a fresh ticket:

@YourBot I want to order something, what info do you need from me?

Expected result: AIO sends the strict workflow checklist instead of a general chat response.

Strict Workflow Does Not Capture Plain Answers

Current builds apply plain replies to the last field AIO asked for. If AIO asks What is the deadline or urgency? and the customer replies take your time, that reply becomes the deadline value.

If the bot still skips the value:

• Confirm tickets.strict_workflow.enabled is true.
• Restart AthenaBot after updating the plugin.
• Test in a new ticket so old session state is not reused.
• Use /aio reset in the ticket if you need to clear the current session.

The Bot Prints [SPEC_CONFIRMED]

That marker belongs to the older marker-based spec flow. For strict workflow setups, keep tickets.enable_spec_confirmation_flow false and use tickets.strict_workflow instead.

If the marker appears:

• Update AIO Agent.
• Confirm tickets.enable_spec_confirmation_flow is false.
• Check custom prompt files and addons for instructions to output {{spec_confirmation_marker}}.
• Restart AthenaBot.

The Bot Cannot Perform An Action

Check:

• The user is in the correct AIO tier.
• The Discord bot has the Discord permission needed for that action.
• The bot’s highest role is above the role/user it is trying to modify.
• The action is not waiting on a confirmation button.
• The action is not blocked by require_confirmation_for, confirm_destructive_tools, or ticket-close policy.

FAQ Does Not Match

FAQ matching uses configured trigger phrases. Add several common phrasings:

faq: {
  enabled: true,
  entries: [
    {
      triggers: ["docs", "documentation", "where are the docs", "doc link"],
      answer: "Docs: https://docs.havendevelopment.net/"
    }
  ]
}

If the question needs reasoning or product context, put it in the knowledgebase instead of FAQ.