CommonIssues.md

Troubleshooting: Common Issues

Here are some common problems users might encounter and potential solutions:

• Log Stream Not Working in Web UI

  • Cause: The real-time log stream uses Server-Sent Events (SSE). Some older browsers might have limited support, or network intermediaries (proxies, firewalls) might interfere.
  • Solution:
    • Try accessing the UI from a modern browser (Chrome, Firefox, Edge, Safari).
    • If using a reverse proxy, ensure it's configured to handle SSE correctly (e.g., disable response buffering for the /logs endpoint, ensure appropriate timeouts). Check your specific proxy's documentation for SSE or streaming requests.
    • Check browser developer console (F12) for errors related to SSE connections.

• Reverse Proxy Issues (General)

  • Cause: Incorrect configuration of the reverse proxy handling requests to the DockFlare UI (port 5000).
  • Solution:
    • Ensure the proxy correctly forwards requests to http://dockflare-container:5000.
    • Ensure WebSocket connections (if used by any future UI features, though primarily SSE is used now) and SSE are proxied correctly.
    • Check headers like Host, X-Forwarded-For, X-Forwarded-Proto are being set appropriately by the proxy.
    • Ensure the proxy isn't stripping or overly modifying necessary headers, including potentially CSP headers.

• Container Not Being Detected / Rule Not Created

  • Cause: DockFlare isn't picking up your container's labels or cannot configure the rule.
  • Verification Steps:
    1. Labels Correct? Double-check the labels on your target container (docker inspect <container_name>).
       • Is cloudflare.tunnel.enable (or your custom prefix) set to exactly "true" (as a string)?
       • Are hostname and service labels present and correctly formatted?
       • Are indexed labels sequential (0, 1, 2...) with no gaps?
       • Is the prefix correct (cloudflare.tunnel. or your LABEL_PREFIX)?
    2. Network Access? Is the target container on a network that DockFlare can access?
       • By default, DockFlare (and its internal cloudflared agent) are on cloudflare-net. Is your target container also attached to cloudflare-net?
       • Alternatively, did you set SCAN_ALL_NETWORKS=true in DockFlare's environment variables? (Use with caution, might have performance implications).
       • Is the service label using a hostname/container name that is resolvable from within the DockFlare/cloudflared container's network scope (e.g., http://container-name:port)? Using IP addresses might be more reliable if network/DNS issues are suspected.
    3. Valid Hostname/Service?
       • Is the hostname a valid FQDN (e.g., my-app.example.com) within a zone managed by your Cloudflare account?
       • Is the service format correct (protocol://host:port, e.g., http://my-app:80, https://backend:443)?
    4. DockFlare Logs? Check the DockFlare logs (Web UI or docker logs dockflare) for errors related to container detection, label parsing, DNS creation, or tunnel configuration updates.
    5. API Permissions? Does your CF_API_TOKEN have the required permissions (Zone:DNS:Edit, Account:Cloudflare Tunnel:Edit)?

• Error Creating DNS Record / Tunnel Rule

  • Cause: Cloudflare API errors, often related to permissions, rate limits, or invalid configuration.
  • Solution:
    • Check DockFlare logs for specific error messages from the Cloudflare API.
    • Verify API Token permissions.
    • Check if you might be hitting Cloudflare API rate limits (HTTP 429 errors). See Performance Tuning.
    • Ensure the hostname is valid and within a zone associated with your CF_ZONE_ID or the specified zonename.
    • Ensure the service URL is correctly formatted.

• Rule Stuck in "Pending Deletion"

  • Cause: The cleanup process might not have run yet, or there was an error during deletion.
  • Solution:
    • Wait for the CLEANUP_INTERVAL_SECONDS to pass for the cleanup job to run again.
    • Check DockFlare logs for errors during the cleanup/deletion process.
    • Use the "Force Delete" button in the Web UI as a last resort.