Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add note about cloudflared Android limitation and native workaround

Open Beginner friendly
  • Is something wrong?
#34,428 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
67/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
android, go, rust
Domain
documentation

Research direction

Find the Quick Tunnel or Tunnel troubleshooting documentation page mentioned in the issue and check where platform limitations are documented. Add a concise note covering the Android limitation and the proposed workaround link; confirm the wording is accurate and the note appears in the relevant documentation page.

Written by the indexing model from the issue text.

Description

content:edit documentation effort:high
Existing documentation URL(s)

The Cloudflare Tunnel documentation does not currently mention that cloudflared (the official Go client) does not work on Android without root, due to a DNS resolver issue ([::1]:53 SRV lookup failure).

This is a known, long-standing issue (see cloudflare/cloudflared#1229). For users who want to run a Quick Tunnel on Android, there is currently no official guidance.

I have built a working solution using a pure-Rust QUIC client (forked from cloudflare-quick-tunnel-rs) with JNI bindings and a custom DoH resolver. The project is open source (Apache 2.0): https://github.com/ai-tech-db/ghostchat

I suggest adding a short note to the Tunnel troubleshooting or Quick Tunnel documentation page, stating that:

  1. cloudflared is not supported on Android without root.
  2. A native Android workaround exists (with a link to the project, if appropriate).

This would help Android users avoid hours of debugging and provide a clear path forward.

What changes are you suggesting?

  1. What change I'm suggesting:
    Add a "Known limitations" or "Troubleshooting" note to the Cloudflare Tunnel documentation (specifically for Quick Tunnels) stating that the official cloudflared client does not work on Android without root, due to its DNS resolver attempting lookups on [::1]:53.

  2. Why the docs should be changed / Use cases:
    Many users try to run cloudflared directly on their Android phones (often via Termux) to expose local services or use Quick Tunnels. They hit a wall with the error lookup api.trycloudflare.com on [::1]:53: read: connection refused.

Currently, the documentation offers no guidance on this, leading to hours of frustration and dead-end forum threads. A note here would save Android users time and set the correct expectations (i.e., that running the official Go client requires root or a workaround).

  1. Expected outcome:
    Users reading the Tunnel docs will immediately know that native Android support is limited. The documentation will also point them to a known workaround: instead of using the Go binary, developers can use a pure-Rust QUIC client with a custom DoH resolver to run Quick Tunnels natively on Android without root.

(For reference, I built an open-source implementation of this workaround: https://github.com/ai-tech-db/ghostchat)

Additional information

Here is a technical breakdown of why the workaround was necessary and how it works.

The error occurs because the Go-based cloudflared binary bypasses the system resolver and tries to reach a local DNS server on [::1]:53 for SRV lookups. On non-rooted Android, no service listens on port 53.

To solve this, I bypassed the Go binary entirely and used a pure-Rust QUIC client (cloudflare-quick-tunnel-rs). To make it work on Android, I had to implement three specific fixes:

  1. DoH (DNS over HTTPS): Configured a custom hickory-resolver to fetch DNS records over port 443, completely bypassing the carrier/OEM DNS filtering and the [::1]:53 requirement.
  2. JNI (Java Native Interface): Wrote a C wrapper and Rust FFI bindings to call the QUIC client directly from Flutter/Dart.
  3. Webpki-roots: Bundled Mozilla's root CA certificates directly into the binary, because Android does not ship with /etc/ssl/certs/ca-certificates.crt (which the Rust TLS stack expects by default).

The implementation is open source (Apache 2.0) if the team wants to look at the JNI/Rust bridge for reference:
https://github.com/ai-tech-db/ghostchat/tree/main/rust/cloudflare-quick-tunnel-rs

Dominant language
MDX
Stars
5.3k
Forks
17.1k
Avg merge
1d 15h
Merged PRs (30d)
556

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cloudflare/cloudflare-docs

All issues in cloudflare/cloudflare-docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.