3.9 KiB
Troubleshooting
Health and diagnostics
curl -s http://127.0.0.1:8081/healthz # "ok" when the process and database respond
journalctl -u active-push -f # server log
sudo -u active-push active-push device list
active-push probe --url https://mail.example.com/Microsoft-Server-ActiveSync --user jan@example.com
probe performs OPTIONS, Provision, FolderSync and an Inbox Sync like a phone would. Use --device-id,
--device-type and --model to imitate a specific device. For protocol-level detail add the mailbox to
ActiveSync -> Logging -> Debug users; decoded WBXML of every request/response then appears in the log.
After migrating from Z-Push: "collection ... not found" in the live stream
Phones may keep folder ids created by Z-Push (e.g. a6271970). ActivePush answers such a Sync with status 12
(hierarchy changed), remembers the id and sends a FolderHierarchy Delete for it on the device's next
FolderSync, so the phone drops the phantom folder and continues with the real ones. If a device still loops
after a few minutes, use Full resync in the device dialog or remove and re-add the account on the phone.
Device keeps asking for the password / HTTP 401
- Wrong password, or the login format does not match IMAP (
general.login_format,default_domain). - The account or IP may be locked out: Mailboxes -> Active login lockouts shows and clears lockouts.
- Check
authentication failed user=... ip=...lines in the log.
HTTP 449 or status 142/144
The device has not accepted the current policy. It normally re-provisions automatically. If a device cannot apply the policy (e.g. it does not support encryption), relax the policy or enable loose provisioning.
Push is late
Push latency is at most ping.check_interval_secs (default 30 s). The reverse proxy must allow long requests
(proxy_read_timeout 3660s, buffering off). The Live page shows every held Ping and its heartbeat.
HTTP 503 with Retry-After
The IMAP server was unreachable during the request. Check the Backends page test buttons.
Panel is not reachable
The panel listens on loopback by default; use ssh -L 9091:127.0.0.1:9091 server. Starting it on another
address requires ACTIVE_PUSH_ALLOW_REMOTE_ADMIN=true (preferably with TLS). Lost password:
sudo -u active-push active-push admin reset-password.
"belongs to uid ..." when running a command
CLI commands must run as the service user so database files keep the right owner:
sudo -u active-push active-push ....
iPhone still asks for the server address
iOS only runs Autodiscover when it can reach it for the domain of the e-mail address. It tries, in order,
https://<domain>/autodiscover/autodiscover.xml, https://autodiscover.<domain>/autodiscover/autodiscover.xml
and the DNS SRV record _autodiscover._tcp.<domain>; a failure is silent and the phone shows the manual
"Server" field. Run the diagnostics on the Autodiscover page first (it checks DNS, SRV and every endpoint). Then open Live while adding the account:
| What you see | Meaning / fix |
|---|---|
| nothing at all | the request never reaches ActivePush: no DNS record for autodiscover.<domain>, a certificate that does not cover that name, or no nginx server_name / locations for it. Add the name to the certificate and the three location blocks (see deploy/nginx-active-push.conf) |
401 auth required, then nothing |
iOS did not accept the answer or the TLS certificate; check the certificate chain with a browser |
503 backend unavailable |
IMAP login check failed, see Logs |
200 ok (host) but the phone still asks |
the returned URL is built from the host the request arrived on (e.g. autodiscover.example.com); set Autodiscover -> Public ActiveSync URL to the public ActiveSync URL that has a valid certificate |
The e-mail address typed on the phone must be a full address (user@domain); the login is derived from it
according to the Login settings.