Help · Troubleshooting

Troubleshooting

Agent problems have their own page.

The Mac still went to sleep

• Was a stop-blocking rule the cause? The journal says “Blocking released — …” with the reason: lid closed, screen lock, display sleep, screensaver, low battery, user switch. Turn the rule off in Settings ▸ Keep Awake if that is not what you want.
• Was a timer running? It sleeps the Mac at zero by design.
• Did an agent ask for sleep after its task? “Mac put to sleep” in the journal, with the agent’s task name above it.

The Mac did not sleep after an agent finished

• Did the agent say deferred? Another agent is still working; the Mac sleeps after the last one.
• Did the agent report an error at the end (call_failed, shortcuts_unavailable, a timeout)? macOS asks once before each AtControl shortcut may run, and a question nobody answers stops it. At the Mac, ask your agent to go through the AtControl shortcuts and choose Always Allow for each — see Setting your agent up, step 5.

The screensaver started

Check Settings ▸ Keep Awake ▸ “The screensaver starts anyway” (off by default) — with it on, a hot corner wins and blocking ends; with it off, the screensaver should not start while blocking. If it does, tell us the macOS version.

The phone says Offline, but the Mac is on

• Is AtControl running on the Mac, with iPhone sync on? The Mac only speaks while the app runs.
• “Last seen” vs “Checked iCloud”: if Checked iCloud is old too, the phone has not been able to read at all — pull to refresh, check the phone’s network and its iCloud account (Settings ▸ Apple Account ▸ iCloud must be on for this app).
• After the Mac wakes, it publishes “awake” and retries for about a minute; the network is often not back yet. Give it a minute.
• Asleep means silent: a sleeping Mac publishes nothing, so “Last seen” stops moving. That is correct; it is not offline.

Pairing fails

• No Mac found: press Pair an iPhone… on the Mac first — a Mac with no phone paired is not in iCloud until then. Same iCloud account on both? The Mac’s Settings ▸ iPhone tab says whether the account is usable and why not (signed out, restricted, not ready).
• “Start pairing on the Mac” greyed: press Pair an iPhone… on the Mac; the window lasts ten minutes.
• “The pairing window on the Mac is closed or expired”: start it again.
• “That pairing code belongs to a different Mac”: you tapped the wrong Mac in the list.
• Stuck on “Waiting for the Mac to confirm…”: leave the sheet open a few seconds; if it never returns, cancel, restart the pairing window on the Mac, try again. Report it with both build numbers.

A command never completed

The phone tells you what it knows: waiting, unconfirmed after a minute, expired. Common causes: the Mac fell asleep (delivery is not guaranteed while asleep), the Mac app was quit, or iCloud throttled delivery. The Mac checks every 30 seconds while awake; the command is recorded on both sides and is never repeated automatically.

No alerts arrive on the phone

• iOS notifications for AtControl on? The Settings screen shows an orange row if not.
• The category on? Also notify me about — and for the alarm, the idle threshold and the “only if locked” rule.
• A Focus on? Turn on Break through Focus for the alarm.

“Update AtControl” / “Update AtControl on your Mac”

The two apps disagree about the wire format. Update the one named; controls stay off until then. This is not an outage.

The window keeps popping up while an agent works

Settings ▸ Agents ▸ Behavior ▸ Bring AtControl to the front: For sleep and shutdown (the default) keeps ordinary commands behind. If they still come forward, a second installed copy of AtControl may be answering — leave one.

Where are the logs?

To send them with a report: Settings ▸ Advanced ▸ Export diagnostics, or Help ▸ Export Diagnostics…. Pick the first day and AtControl saves a plain-text file with the state changes and errors it kept since then (up to 30 days), the detailed log of the current launch, and what it runs on: the Mac model and processor, power source, free disk space and AtControl’s own settings. The file has no network addresses, tokens, pairing secrets, task names or the Mac’s name, and nothing is sent anywhere; read it before attaching it if you like. When AtControl notices a problem worth reporting, a mark appears beside Advanced in the Settings sidebar until you dismiss it.

To watch them live: Console.app, search for app.atControl. The Mac app logs under app.atControl.mac, the channel between Mac and phone under app.atControl.companion, and the iPhone and iPad app under app.atControl.mobile. Pairing links, secrets and tokens are never logged.