Skip to main content

Common Issues

This page collects the most common issues encountered while using Elftia and their solutions. Each issue includes a symptom description, possible causes, and specific troubleshooting steps.

Startup and Interface Issues​

Blank Screen After Starting Application​

Symptom: After opening Elftia, the window shows a blank or white screen with no interface content.

Possible Causes:

  • GPU acceleration incompatibility with graphics card drivers
  • Frontend renderer process crash
  • Corrupted installation files

Troubleshooting Steps:

  1. Close Elftia and start it from the command line with the --disable-gpu parameter to test if it's a GPU issue.
  2. Update your graphics card drivers to the latest version.
  3. Check if there are any leftover Elftia processes in the system. Use Task Manager to terminate all related processes and try again.
  4. If the issue persists, try reinstalling Elftia.

Application Crashes Immediately After Starting​

Symptom: After double-clicking to start, the window flashes and closes immediately.

Possible Causes:

  • Missing system runtime dependencies (such as Visual C++ Redistributable)
  • Permission issues with the user data directory
  • Conflicts from leftover data from an older version

Troubleshooting Steps:

  1. Windows: Install the latest version of Visual C++ Redistributable.
  2. Check if the user data directory has write permissions.
  3. Try deleting cache files in the user data directory and restart (conversation data will not be lost).
  4. Run Elftia with administrator privileges.

Garbled Text in Interface​

Symptom: Text in the interface displays as boxes or gibberish.

Possible Causes:

  • Custom font settings specified a font not installed on the system
  • Corrupted font files

Troubleshooting Steps:

  1. Open Settings → Appearance and clear the custom input fields for UI Font and Code Font.
  2. If you cannot access the Settings page, manually delete the theme configuration file in the user data directory.

LLM Provider Issues​

Provider Test Connection Failed — 401​

Symptom: Test connection shows 401 Unauthorized or Invalid API Key.

Possible Causes:

  • API Key entered incorrectly (extra spaces, missing prefix, etc.)
  • API Key has expired or been revoked
  • Using an API Key from the wrong provider

Troubleshooting Steps:

  1. Re-copy your API Key and ensure there are no extra spaces or line breaks.
  2. Go to the provider's console to confirm the Key is still valid.
  3. Confirm the API Key matches the correct provider.

Provider Test Connection Failed — 403​

Symptom: Test connection shows 403 Forbidden.

Possible Causes:

  • Account balance is insufficient or no payment method is linked
  • API Key does not have sufficient permissions (e.g., read-only key)
  • IP address is blocked by the provider

Troubleshooting Steps:

  1. Check your provider account's balance and payment status.
  2. Confirm that your API Key has permission to call models.
  3. If using a proxy, try switching to a different proxy node.

Provider Test Connection Timeout​

Symptom: Test connection has no response for a long time and eventually times out.

Possible Causes:

  • Network connectivity issues
  • Incorrect proxy configuration
  • Firewall blocking outbound requests

Troubleshooting Steps:

  1. Check if your network connection is normal.
  2. If using a proxy, confirm the proxy is running and configured correctly (see Using Proxy).
  3. Confirm your firewall allows Elftia to access the internet.
  4. Try accessing the provider's API domain directly in a browser (e.g., api.openai.com) to confirm the domain can be resolved.

Stream Reply Interrupted​

Symptom: The AI reply stops midway, resulting in incomplete messages.

Possible Causes:

  • Unstable network connection causing SSE stream interruption
  • Response reaches the model's maximum token limit
  • Proxy connection timeout setting is too short

Troubleshooting Steps:

  1. Try regenerating the reply.
  2. If it happens repeatedly, check network connection stability.
  3. Confirm your proxy (if used) has a timeout setting of at least 120 seconds.
  4. Reduce the max_tokens value in model parameters, or split long reply requests.

Agent Tool Cannot Execute​

Symptom: Agent attempts to use a tool (such as Bash, Write, etc.) but shows permission denied.

Possible Causes:

  • GuardianAgent is set to strict mode blocking operations
  • Permission mode is set to "Plan Only"
  • Operation is blocked by deterministic rules in the execution firewall

Troubleshooting Steps:

  1. Check Settings → Clawia → GuardianAgent Mode and lower the security level as needed.
  2. Check if the permission mode is set to "Plan Only".
  3. View the Audit Log to confirm which security layer blocked the operation.

Agent Tool Execution Failed — command not found​

Symptom: Agent executing a Shell command shows command not found.

Possible Causes:

  • Required command-line tool is not installed on the system
  • Environment variable PATH does not include the tool path

Troubleshooting Steps:

  1. Open Settings → General → Environment and check the installation status of the tool.
  2. Install any missing tools (Node.js, Git, etc.).
  3. If the tool is installed but still not found, you may need to restart Elftia to refresh environment variables.

MCP Server Cannot Connect — stdio Mode​

Symptom: Added MCP server shows connection failure using stdio (subprocess) mode.

Possible Causes:

  • Command does not exist or path is incorrect
  • Dependencies not installed (e.g., Node.js package not installed)
  • Missing environment variables

Troubleshooting Steps:

  1. Confirm the MCP server's command can be run directly in a terminal (e.g., npx -y @modelcontextprotocol/server-filesystem /path).
  2. Check if Node.js is installed (node --version) or Python (python --version).
  3. If the MCP server requires additional environment variables (such as API Keys), confirm they are correctly set in the MCP configuration's env.
  4. Restart Elftia and try again.

MCP Server Cannot Connect — SSE/HTTP Mode​

Symptom: Remote MCP server connection times out or is refused.

Possible Causes:

  • MCP server is not running
  • Incorrect URL or port
  • Network/firewall blocking the connection

Troubleshooting Steps:

  1. Confirm the MCP server is running and accessible.
  2. Check if the URL format is correct (includes http:// or https:// prefix).
  3. If using a proxy, confirm proxy rules allow access to the MCP server address.

Channel Bot Not Responding​

Symptom: Sending a message through Discord/Telegram or other platforms, but the bot does not reply.

Possible Causes:

  • Trigger rule not matched (e.g., requires @mention but was not @)
  • Message blocked by PromptGuardian
  • Channel not started or Token configured incorrectly
  • Rate limit triggered

Troubleshooting Steps:

  1. Confirm the message meets the Channel's trigger rules (@mention, keywords, prefix, etc.).
  2. Check PromptGuardian mode and temporarily set to "Off" to test if it's a false positive in injection detection.
  3. Confirm the Channel's Bot Token is correct and the Bot is online.
  4. Check the audit log for any blocked message records.

Media Generation Issues​

Image/Video/Music Generation Failed​

Symptom: Error when requesting media content generation.

Possible Causes:

  • Corresponding media generation provider is not configured or has insufficient balance
  • Request content was rejected by the provider's security filter
  • Network connectivity issue

Troubleshooting Steps:

  1. Confirm the provider used for media generation is correctly configured and has sufficient balance.
  2. Try simplifying or modifying the generation prompt to avoid sensitive content.
  3. Check your network connection and proxy configuration.

Display Issues​

Wallpaper Set But Text Not Readable​

Symptom: After setting a wallpaper, some interface text is difficult to read due to high transparency.

Troubleshooting Steps:

  1. Increase the Mask Opacity value (recommended 70-85).
  2. Increase the Blur Strength value (recommended 8-15).
  3. If specific areas are still not readable, use custom CSS to adjust.

Interface Elements Invisible in Dark Mode​

Symptom: In dark mode, some borders, dividers, or text colors are too light and difficult to read.

Troubleshooting Steps:

  1. Try switching to a different accent color. Some colors have better contrast in dark mode.
  2. Check if any custom CSS is affecting color display, and try clearing custom CSS.
  3. Increase your monitor's brightness.

Performance Issues​

High Memory Usage​

Symptom: Memory usage by Elftia continuously grows.

Possible Causes:

  • Too many conversation tabs are open
  • A single conversation contains a large number of messages (hundreds or more)
  • Too many attachments (especially images)

Troubleshooting Steps:

  1. Close unnecessary conversation tabs.
  2. For very long conversations, consider starting a new conversation.
  3. Open Settings → System and execute Clear Caches to clean up cache.
  4. Restart Elftia to free up memory.

Symptom: Database operation errors or data inconsistency.

Troubleshooting Steps:

  1. Open Settings → System and execute VACUUM to optimize the database.
  2. If the issue persists, export diagnostic information (Export Diagnostics) for further investigation.
  3. In extreme cases, the database file (.db) in the user data directory can be safely backed up and replaced.

Abnormality After Update​

Symptom: Application behaves abnormally after updating to a new version.

Troubleshooting Steps:

  1. Open Settings → System and execute Clear Caches and VACUUM in sequence.
  2. Restart Elftia.
  3. If the issue persists, refer to the rollback steps in Update Elftia.

If the above solutions do not resolve your issue, try using the Diagnostic Tools to collect detailed information, or refer to Connection Errors for detailed troubleshooting methods for network-related issues.