Skip to main content

Connection Errors

This page focuses on troubleshooting various network connection issues in Elftia. Covers LLM API call errors, proxy-related failures, SSL/TLS issues, MCP connection failures, and Channel connection anomalies.

LLM API HTTP Status Codes​

When an LLM API call returns an error, the HTTP status code is the most important troubleshooting clue. Here's the meaning of each status code and its solutions:

401 Unauthorized​

Meaning: API Key is invalid or not provided.

Common Causes:

  • API Key contains extra spaces or newlines
  • API Key has been revoked or expired
  • API Key format is incorrect (e.g., OpenAI key should start with sk-)
  • Using a key from the wrong provider

Solution Steps:

  1. Go to Settings → Provider Settings and re-check the API Key.
  2. Copy the complete key and replace the existing value in the input box.
  3. Go to the provider's console and confirm the key is still valid.
  4. If using an API Key pool, check if any keys in the pool are invalid (disabled keys are marked gray).
info

When an API Key in the pool returns 401, that key is automatically disabled, and the system automatically switches to another available key in the pool.

403 Forbidden​

Meaning: Authentication succeeded but insufficient permissions.

Common Causes:

  • Account balance is insufficient or payment method not linked
  • API Key doesn't have access to the requested model
  • IP address or region is restricted by the provider
  • Organization/project permission restrictions

Solution Steps:

  1. Log in to the provider's console and check account balance and payment status.
  2. Confirm the API Key has access to the model you selected (some advanced models require special permissions).
  3. If using a proxy, try switching to a proxy node in a different region.
  4. Check organization and project settings in the provider's console.

429 Too Many Requests​

Meaning: Request frequency is too high, triggering rate limiting.

Common Causes:

  • Too many requests sent in a short time
  • Account has a low rate quota (free or low-tier account)
  • Multiple applications sharing the same API Key

Solution Steps:

  1. Wait a while before retrying. Elftia will display a cooldown notice.
  2. If frequently triggered, consider upgrading your provider account's tier.
  3. Configure an API Key pool using multiple keys to distribute requests.

Elftia's Auto-handling:

  • When encountering 429, the current key enters a cooldown period (starting from 60 seconds, exponential backoff up to 15 minutes).
  • If an API Key pool is configured, the system automatically switches to another available key and retries.
  • The key automatically recovers after the cooldown period ends.

500 Internal Server Error​

Meaning: Provider server internal error.

Solution Steps:

  1. This is a provider-side issue, typically self-resolving. Wait a few minutes and retry.
  2. Check the provider's status page for known incidents.
  3. If it persists, try switching to another model or provider.

502 Bad Gateway​

Meaning: Provider's gateway/load balancer error.

Solution Steps:

  1. Usually a temporary issue; wait 1-5 minutes and retry.
  2. Check the provider's status page.
  3. If using a custom Base URL (third-party relay), check if the relay service is working.

503 Service Unavailable​

Meaning: Provider service is temporarily unavailable (maintenance or overload).

Solution Steps:

  1. Wait for the provider to restore service.
  2. Switch to a backup provider to continue working.
  3. Check the provider's status page and social media for recovery time.

529 Overloaded​

Meaning: Provider server is overloaded (Anthropic-specific status code).

Solution Steps:

  1. Wait a while and retry.
  2. If an API Key pool is configured, the system will automatically switch keys and retry.
  3. Try using a smaller model (e.g., Claude Haiku instead of Claude Opus) to reduce server load.

Elftia's Auto-handling: Same as 429, triggers cooldown and automatic key switching mechanism.

ECONNREFUSED​

Meaning: Connection refused, usually the proxy service is not running.

Error: connect ECONNREFUSED 127.0.0.1:7890

Solution Steps:

  1. Confirm the proxy client (Clash, V2Ray, Shadowsocks, etc.) is running.
  2. Check if the proxy's listening port matches the port configured in Elftia.
  3. Confirm the proxy is listening on the correct address (127.0.0.1 vs 0.0.0.0).
  4. If you don't need a proxy, switch to "No Proxy" in Settings → General → Proxy.

ETIMEDOUT​

Meaning: Connection timeout; proxy cannot reach the target server.

Error: connect ETIMEDOUT api.openai.com:443

Solution Steps:

  1. Check if the proxy's upstream connection is working (can the proxy access the target domain).
  2. Check if the proxy's routing rules include LLM API domains.
  3. Try switching proxy nodes.
  4. Check firewall rules.

ECONNRESET​

Meaning: Connection reset by remote, usually proxy disconnects mid-stream.

Solution Steps:

  1. Check the stability of your proxy connection.
  2. Increase the proxy's timeout settings.
  3. If it's a long streaming request (e.g., large code generation), the proxy may have connection duration limits that need adjustment.

SSL/TLS Errors​

UNABLE_TO_VERIFY_LEAF_SIGNATURE​

Meaning: Cannot verify server certificate, usually a self-signed certificate.

Common Scenarios:

  • Corporate proxy uses self-signed CA certificate for HTTPS inspection
  • Self-built LLM API relay service uses self-signed certificate

Solution Steps:

  1. Install and trust the certificate from the proxy/relay service.
    • Windows: Double-click certificate file → Install Certificate → Local Machine → Trusted Root Certification Authorities.
    • macOS: Double-click certificate file → Add to Keychain → Always Trust.
    • Linux: Copy to /usr/local/share/ca-certificates/ → Run sudo update-ca-certificates.
  2. Restart Elftia for certificate changes to take effect.

CERT_HAS_EXPIRED​

Meaning: Server's SSL certificate has expired.

Solution Steps:

  1. If it's a self-built service, update the SSL certificate.
  2. If it's a public service, it's usually temporary; retry later.
  3. Check if system time is correct (incorrect system time can cause valid certificates to be marked as expired).

ERR_TLS_CERT_ALTNAME_INVALID​

Meaning: Certificate's domain doesn't match the actual access domain.

Solution Steps:

  1. Check if the provider's Base URL is spelled correctly.
  2. If using a custom endpoint, ensure the server certificate covers the domain you're using.

MCP Connection Errors​

stdio mode — ENOENT​

Meaning: Cannot find the MCP server startup command.

Error: spawn npx ENOENT

Solution Steps:

  1. Confirm the program specified in the command field is installed:
    • npx / node: Need to install Node.js.
    • uvx / python: Need to install Python and uv.
  2. Manually run the command in terminal to verify if it's executable.
  3. Check the installation status of tools in Settings → General → Environment.
  4. If the tool is installed but still errors, you may need to restart Elftia to refresh PATH environment variables.

stdio mode — Process exits immediately after starting​

Symptom: MCP server shows brief connection then disconnects.

Possible Causes:

  • Missing necessary npm/pip dependencies
  • Incorrect startup parameters
  • Missing necessary environment variables

Solution Steps:

  1. Manually run the MCP server command in terminal to see error output: 
    npx -y @modelcontextprotocol/server-filesystem /path
  2. Check for missing dependency packages and install manually: 
    npm install -g @modelcontextprotocol/server-filesystem
  3. Ensure the env in the MCP configuration contains all necessary environment variables.

SSE/HTTP mode — Connection timeout​

Symptom: Remote MCP server connection times out.

Solution Steps:

  1. Confirm the MCP server is running and accessible from your network.
  2. Try accessing the MCP server's URL in a browser to verify connectivity.
  3. Check if the firewall allows access to the MCP server's port.
  4. If using a proxy, confirm proxy rules allow access to the MCP server's address.

SSE mode — Connection frequently drops​

Symptom: SSE connection frequently drops and reconnects after established.

Possible Causes:

  • Unstable network
  • Proxy or load balancer connection timeout settings too short
  • MCP server itself is unstable

Solution Steps:

  1. Check your network connection stability.
  2. If using a proxy or reverse proxy, increase connection timeout and idle timeout settings.
  3. Contact the MCP server maintainer to confirm service status.

Channel Connection Errors​

Discord Bot connection fails​

Possible Causes:

  • Bot Token invalid or expired
  • Bot not invited to target server
  • Bot lacks necessary permissions
  • Discord API rate limiting

Solution Steps:

  1. Confirm Bot Token is correct in Discord Developer Portal.
  2. Confirm Bot is invited to the target Discord server with speaking rights.
  3. Check if the Bot's Privileged Gateway Intents are enabled.

Telegram Bot connection fails​

Possible Causes:

  • Bot Token invalid
  • Network cannot access Telegram API (api.telegram.org)
  • Another client using the same Bot Token

Solution Steps:

  1. Confirm Bot Token is correct through @BotFather.
  2. Confirm your network can access api.telegram.org (may require proxy).
  3. Ensure no other application is using the same Bot Token.

Rate Limiting & Backoff Mechanism​

Elftia has built-in intelligent rate limiting handling:

API Key Pool Auto-Switching​

When a single key encounters 429/529 errors:

  1. Current key enters cooldown period.
  2. System immediately tries the next available key in the pool.
  3. If request succeeds, user barely notices.
  4. Cooldown uses exponential backoff: 60s → 120s → 240s → ... → max 15 minutes.
  5. Key automatically recovers after cooldown ends.

Session Affinity​

To maintain LLM provider prompt cache efficiency, the same chat session tries to use the same API Key:

  • First request selects key via weighted round-robin.
  • Subsequent requests prioritize the same key.
  • Only switch if the bound key is unavailable (cooling down or disabled).

Permanent Failure Handling​

When a key returns 401/403, the key is permanently invalid:

  • That key is automatically disabled (marked unavailable).
  • System switches to another key.
  • You'll see the disabled key in the provider settings' API Key pool.

Firewall & Antivirus Software​

Firewall blocks outbound connections​

Symptom: All LLM API calls timeout or are rejected.

Solution Steps:

  1. Add Elftia to your firewall's allowlist.
    • Windows Defender Firewall: Control Panel → Windows Defender Firewall → Allow an app through firewall → Add Elftia.
    • macOS: System Preferences → Security & Privacy → Firewall → Allow Elftia.
  2. If using corporate firewall, contact your IT admin to open outbound access to:
    • api.openai.com (OpenAI)
    • api.anthropic.com (Anthropic)
    • generativelanguage.googleapis.com (Google Gemini)
    • api.deepseek.com (DeepSeek)

Antivirus false positives​

Symptom: Antivirus blocks Elftia from running or network connections.

Solution Steps:

  1. Add Elftia's installation directory to your antivirus exclusion/whitelist.
  2. Common paths to exclude:
    • Windows: C:\Users\<username>\AppData\Local\Elftia\
    • macOS: /Applications/Elftia.app

Quick Network Connectivity Check​

When encountering connection issues, troubleshoot in this order:

  1. Basic Network: Open any webpage in browser to confirm network is working.
  2. DNS Resolution: Run ping api.openai.com (or corresponding provider domain) to confirm domain resolution.
  3. Port Connectivity: Run curl -I https://api.openai.com to confirm port 443 is accessible.
  4. Proxy Test: If using proxy, set proxy environment variables in terminal and retry the above commands.
  5. Elftia Test: Use "Test Connection" in Elftia's provider settings.

If steps 1-4 succeed but step 5 fails, it may be Elftia's proxy configuration issue; see Using Proxy to reconfigure.

If this page doesn't cover the connection issue you're experiencing, use the Diagnostic Tools to export diagnostic information and seek help in the community.