Troubleshooting
Every error says what happened and what to do next. Here are the ones you’re most likely to see, with the fix.
“No Dukoi phone found on this Wi-Fi”
Open Dukoi on the phone and check both are on the same Wi-Fi. Guest networks and some mesh routers stop devices finding each other. Pass the phone’s address instead: dukoi pair --host 192.168.0.112.
“The phone at … is not reachable”
Check the phone is on, on the same Wi-Fi, and Dukoi is running. If all that’s fine and commands worked before, the phone’s address probably changed. Run dukoi pair again, then give the phone a fixed address on your router (a DHCP reservation) so it doesn’t happen again.
“Your app started but didn’t answer on PORT”
Dukoi waits 10 seconds for your app to answer on PORT. Check that it listens on process.env.PORT, not a fixed port, and read dukoi logs for errors. If it’s a bot or worker with no port, deploy with --no-health-check. The old release keeps running until a new one is healthy.
“Your start script runs …, but the phone can only run Node directly”
The phone runs node, not tsx, bun or npm. Add a build script that compiles your app, and make scripts.start node dist/server.js. Deploy runs the build on your computer first.
“… uses native code, which phones can’t run yet”
Swap the package for a pure JavaScript one. The error suggests one: bcryptjs for bcrypt, node:sqlite for better-sqlite3, jimp for sharp.
Apps keep restarting
Run dukoi ps. It says why each app last stopped. If Android is stopping it, open Dukoi on the phone and finish any setup step that isn’t green, especially the steps for your phone’s brand. See Set up the phone.
My quick link changed
Quick links change whenever the tunnel restarts. dukoi ps shows the current one. For a URL that never changes, use your own domain.
Cloudflare says “Quota limit exceeded”
Cloudflare allows 50 API tokens per account, and each login adds one. Delete the ones you don’t use at dash.cloudflare.com → My Profile → API Tokens, then run the command again.
Still stuck?
Open an issue on GitHub with the command you ran and what it printed. Add --json to get the error code.