troubleshooting

agent won't connect to cloud

Symptoms: Machine shows offline in dashboard, agent logs show connection errors.

Check:

1. Verify internet connectivity on the agent machine
2. Check firewall rules — outbound HTTPS (port 443) must be allowed to owlette.app, dev.owlette.app, *.googleapis.com, *.firebaseio.com, and the Cloudflare R2 endpoint used for roost chunks (usually *.r2.cloudflarestorage.com)
3. Check C:\ProgramData\Owlette\logs\service.log for specific errors
4. Verify firebase.enabled is true in config.json
5. Verify firebase.site_id matches a site that exists in Firestore

Common errors:

dashboard shows machine offline

Symptoms: Agent is running but dashboard shows offline.

1. Check heartbeat age — If last seen was recently, the machine may be experiencing intermittent connectivity
2. Check agent service: sc query OwletteService (should show RUNNING)
3. Check ConnectionManager state in logs — look for BACKOFF or DISCONNECTED
4. Verify site_id — Agent and dashboard must be looking at the same site
5. Check Firestore directly — Go to Firebase Console → Firestore → sites/{siteId}/machines/{machineId} → check the machine document fields online, lastHeartbeat, agent_version, and metrics

processes not auto-restarting

1. Verify launch_mode is always, or scheduled with the current time inside a configured schedule window
2. Check if relaunch_attempts limit was reached (reboot prompt should appear)
3. Verify exe_path exists on the machine (INACTIVE state means file not found)
4. Check agent logs for launch errors
5. Verify the service is running and the main loop is executing (look for periodic log entries)

process won't launch after an app upgrade

Symptoms: A managed process shows INACTIVE, or the dashboard shows an executable-missing toast after software was upgraded or installed side-by-side.

1. Open the dashboard toast or activity log entry with action exe_missing.
2. Review the suggested paths. The agent scans nearby sibling directories for executables with the same filename.
3. Use the toast's use path action, or open the process edit dialog manually and update executable path.
4. Save the process. If launch mode is always, the agent should launch it on the next monitoring pass. If launch mode is scheduled, it launches when the next matching schedule window opens.
5. If no suggestion appears, browse the machine for the new executable path and update the process manually.

oauth token issues

"agent not authenticated - no refresh token found"

The encrypted token file is missing or unreadable.

Fix: Re-pair the agent:

1. Delete the token file: del C:\ProgramData\Owlette\.tokens.enc
2. Run the pairing flow: C:\ProgramData\Owlette\python\python.exe C:\ProgramData\Owlette\agent\src\configure_site.py
3. The console prints a 3-word pairing phrase and the authorization link for the server this machine is bound to, then starts polling. Open that link from any device and enter the phrase — nothing opens a browser here on its own. The running service picks the new credentials up on its own; no restart is needed.

token refresh failing

Check service.log for refresh errors. Common causes:

• Machine ID mismatch — The machine was renamed since registration
• Token revoked — An admin revoked the token from the dashboard
• Network issue — Can't reach the refresh endpoint

deployment stuck

Symptoms: Deployment shows "downloading" or "installing" indefinitely.

1. Check agent logs for download/install progress
2. Verify the installer URL is accessible from the agent machine (test in browser)
3. Check if the installation timed out (default: 40 minutes)
4. For large installers on slow connections, the download may simply be slow
5. Try cancelling and re-deploying

roost sync failed

1. R2 configuration failed — Check web runtime logs for missing R2_S3_ENDPOINT, R2_S3_ACCESS_KEY_ID, or R2_S3_SECRET_ACCESS_KEY. The endpoint should be reachable from the web app and agents over HTTPS.
2. Chunk upload or verification failed — Retry the upload from the roost page and confirm the agent machine can reach signed R2 URLs. A publish can fail if the version references chunks that were not uploaded or were rejected after hash verification.
3. Target fanout stalled — Check sites/{siteId}/roosts/{roostId}/target_state/{machineId}. Current target states include pending, downloading, assembling, committed, failed, and cancelled.
4. sync_pull stuck or failed — Check service.log on the target machine for sync_pull errors. If no target-state document appears, confirm the machine is online and has a pending command in sites/{siteId}/machines/{machineId}/commands/pending.
5. Permission denied — The configured extract root may not be writable or may be outside the agent's allowed extract roots.

2fa issues

lost authenticator

If you also have a passkey on the account, sign in with it — a passkey clears 2FA on its own, no code needed.

Otherwise use one of your backup codes at the 2FA prompt. Each code can only be used once.

no backup codes

Ask a superadmin to run reset 2FA on your account from the admin users page (POST /api/users/{uid}/mfa-reset). It removes every second factor — authenticator app, passkeys, and the backup codes — re-arms mandatory 2FA setup, and revokes the account's trusted devices, so the next sign-in starts enrollment from scratch.

Two things it deliberately does not do: it does not revoke Firebase refresh tokens, so a session the user already holds elsewhere stays signed in until it expires on its own; and superadmins cannot reset themselves, so a locked-out superadmin needs a different superadmin to do it.

Because a reset hands the account to whoever signs in next, confirm who you're talking to before running one.

code not working

• Ensure your device's clock is synchronized (TOTP is time-based)
• Codes expire every 30 seconds — enter the current one
• Verify you're using the correct account in your authenticator app

"verify a factor you already have" when adding one

Adding a second factor to an account that already holds one requires the current session to have cleared a 2FA challenge — the route answers 403 with mfa_challenge_required otherwise. Verify with your existing passkey, or take the use a code instead link to /verify-2fa, then add the new factor.

can't regenerate backup codes

Regeneration needs live proof in the same request: a current 6-digit code, an unused backup code, or your passkey. Being signed in is not enough — a fresh sheet of recovery codes could otherwise be used to turn 2FA off entirely. If you have none of the three, that's the superadmin reset above.

asked to set up 2fa again

You removed your last second factor. That's allowed, but the account immediately re-arms 2FA setup, so the dashboard sends you to /setup-2fa to enroll a new factor — a passkey or an authenticator app — before you can use it again. Trusted devices are revoked at the same time.

hoot not responding

1. No LLM key configured — Check hoot settings for API key
2. Invalid API key — Verify the key is correct and has credits
3. Machine offline — hoot checks machine status before executing tools
4. A tool is stuck — A turn keeps running even if you reload the page (the chat reattaches to it), so you rarely lose work. If a tool call is taking too long, use the cancel control on its tool card to kill it, or stop the whole turn from the chat.
5. Rate limited — The API may be rate-limiting requests

email alerts not working

1. Verify RESEND_API_KEY environment variable is set in Railway
2. Check that the Resend API key is valid
3. Verify CRON_SECRET is configured for health check cron
4. Check the cron-job.org schedule is set: */5 * * * *
5. Send a test email from Admin Panel → Email Test
6. Check spam/junk folders

dashboard performance issues

slow loading

• Cold starts (Railway Hobby plan) — Upgrade to Pro for no cold starts
• Large dataset — Many machines/processes increase Firestore reads
• Bundle size — Check .next/static output during build

real-time updates not working

• Check browser console for Firestore listener errors
• Verify Firebase config is correct
• Try hard refresh (Ctrl+Shift+R)
• Check if the Firestore quota has been exceeded

log locations

agent logs

The full inventory, including what each file is good for, is in agent troubleshooting.

dashboard logs

firestore logs

debug mode

Run the agent in debug mode for detailed console output:

cd C:\ProgramData\Owlette\agent\src
python owlette_service.py debug

Requires an elevated (Administrator) command prompt. Shows real-time logging of all service operations.

getting help

1. Check the relevant section of this documentation
2. Review agent logs and browser console for specific error messages
3. Check the Firestore Data Model to verify data structure
4. Open an issue on GitHub
5. Email us at support@owlette.app