Help

Troubleshooting

Common issues, grouped by area. Most come down to one of two things: the app isn't actually running where you think, or a step (DNS, domain verification, publishing) hasn't completed yet.

Connecting

Stuck on "Connecting" or "Opening machine." Your machine may still be waking the desktop session — give it a moment to reach Live. The machine itself is always on; it's the session that's opening. If it stalls, check your network and try again.

"Session interrupted." The connection dropped. Choose Try again. Your machine and everything running on it are unaffected — this is only the view onto it.

Typing feels stale after I've been away. After a long idle, the client refreshes the stream when you return. Give it a beat, or interact once to trigger the refresh. You won't lose the session.

The desktop looked asleep before I signed in. That's the desktop session, not the machine. The machine and your running apps stay on the whole time.

Running and exposing an app

wrkr expose gave me a URL but it doesn't load. wrkr expose publishes a running port — it doesn't start your app. Confirm your app is actually listening on that port first (load http://localhost:<port> in the machine's own Chrome), then expose it.

I exposed the wrong thing / want to stop serving.

wrkr expose list                    # see what's currently exposed
wrkr expose remove <host-or-name>   # stop serving it

Custom domains

My custom domain isn't serving. Two things have to land: the CNAME your agent gave you is added at your registrar, and DNS has propagated (which can take a while). Ask your agent to re-check the record and the domain's status.

Email

Mail from my own domain isn't sending. Using your own domain takes a moment to activate: your agent adds the domain and gives you a couple of DNS records to paste at your registrar, then verifies it once they've propagated. Until that's done, send from the instant Wrkr address, which works immediately — ask your agent to check the domain's status.

Where's my inbox? A person can't log in to read mail. There isn't one — wrkr email is app email, not a human mailbox. To let a person read messages, forward to a real inbox (wrkr email forward …) or webhook the mail into your own app (wrkr email inbound … --webhook …). See Email.

A retried send worried me about duplicates. Pass --idempotency-key and a retry with the same key won't double-send.

Database

My app can't connect to Postgres. Use the exact URL from wrkr db. For LISTEN/NOTIFY and transactions, use the direct URL; for lots of short-lived connections, use wrkr db --pooled.

A migration went wrong. Restore a snapshot: wrkr db restore <snapshot-id> --yes (take one before risky changes with wrkr db snapshot). See Database.

Cache

Data I put in the cache disappeared. That's expected — the cache is Redis with LRU eviction and is not durable. Anything that must persist belongs in the database.

Storage

A stored file returns 403 / isn't publicly readable. Objects are private by default. Publish one explicitly:

wrkr storage url <key> --public     # stable public URL

For a temporary link instead, use a presigned URL: wrkr storage url <key> --expires <seconds>. See Storage.

A very large file won't upload. Uploads are single-PUT; there's no resumable/multipart upload for very large files (roughly over 5 GB) yet.

Files & clipboard (clients)

Full how-to for copy, paste, and transfer in both directions: Files & clipboard.

Files I dragged in didn't show up. They stream into your machine's Files folder. Check there. In the browser client, use the explicit Upload/Download actions instead of drag.

Paste isn't working. The app receiving the paste owns the paste key: most Linux GUI apps use Ctrl-V, terminals use Ctrl-Shift-V, Mac apps use ⌘V. On the native desktop, ⌘V is reserved for Finder-style file paste. See Connecting.

Scheduled jobs

A scheduled job didn't run (or ran but did nothing). Tell your agent — "my nightly job didn't run, can you check it?" Scheduled jobs run in a bare environment, so the usual causes are a missing full path, an environment variable that wasn't loaded, or output that wasn't logged anywhere visible. Your agent knows these and will fix the schedule on your machine. See Cron.

Resources

Things feel slow, or I'm out of space. Check wrkr status — it tells you whether you're within your plan (it watches memory). Your app and its whole stack share one machine, so treat it like any single server — cache hot paths, index queries, and clean up large files.

Getting help

Every client can generate a support report from its System/Help control (the native app's System popover, or the browser Desktop's help panel) — it bundles diagnostics without exposing anything sensitive in your normal view.

Still stuck? Email support@wrkr.dev with your support report attached — a human reads it.