Troubleshooting

First, ask Cloud Butler what's connected

In a chat with Cloud Butler switched on, ask "What can Cloud Butler reach in my iCloud right now?" Your agent runs icloud_get_capabilities, which names the Apple account that is connected and lists what is and isn't available, with the reason. That answers most questions below.

"Apple didn't accept that Apple ID and app-specific password": Check three things: you pasted the app-specific password (four groups of four letters), not your Apple ID password; the Apple ID is the email you sign in to Apple with; and two-factor authentication is on. If in doubt, make a new app-specific password and try again. Changing your Apple Account password removes all app-specific passwords, so you'll need a new one after that.
The Cloud Butler page says "Tick at least one kind of access to connect": You unticked every permission. Tick at least one, or choose Cancel if you don't want to connect.
The Cloud Butler page names an app I don't recognize, or says "a self-registered app (name not verified)": Check that you started connecting from your own AI app just now. If you didn't, choose Cancel. "Not verified" is normal for some apps that register themselves, but the page also shows where access will be sent; it should be your AI app's address.
My AI app says the connector failed to connect, or shows an OAuth error: Remove the connector and add it again with the address exactly as shown in setup, ending in /mcp, and leave the OAuth client settings at their defaults. If your company network blocks unfamiliar sites, try from another network.

Using Cloud Butler

My agent says it can't do something, or doesn't use Cloud Butler at all: Make sure Cloud Butler is switched on for that chat (in Claude: + → Connectors; in ChatGPT: pick it from the + menu). Then mention it: "Use Cloud Butler to check my calendar." If the service really isn't available, the capabilities check above says why.
"… is outside what this connection was allowed to do": You unticked that permission when you connected. Disconnect Cloud Butler in your AI app, connect again and leave that box ticked. How the permissions work.
"… is not available on this person's Cloud Butler plan": That tool acts on your data and is part of Cloud Butler Pro. Free keeps reading your Mail, Calendar and Contacts. See pricing. (During early access, plan checks are off and you won't see this.)
It worked yesterday and stopped today: Most often: the app-specific password was removed (you removed it, or you changed your Apple Account password), or the connection went unused for 30 days. Connect again from your AI app with a new app-specific password.
"Session not found" or the connector suddenly needs reconnecting: After a Cloud Butler update your AI app may need to start a fresh session. Most apps do this by themselves; if not, start a new chat or click Connect again. You don't need a new password.
My agent can't see Drive, Reminders, Notes, Photos or Find My: They aren't offered on the public Cloud Butler service. They'll come through the Cloud Butler app. Why.

Mail

Mail works but Calendar or Contacts don't (or the reverse): If your iCloud Mail address is different from your Apple ID (for example your Apple ID is a Gmail address), disconnect and connect again, entering your @icloud.com, @me.com or @mac.com address in the optional "iCloud Mail address" field. Make sure iCloud Mail is turned on for your account.
"Attachments add up to … the limit is 10 MB": Send fewer or smaller files, or share a link instead. Mail limits.
An attachment from a link won't attach: The link must be a public https address that downloads the file without signing in. Links with a user name or password in them, IP addresses and local network names are refused on purpose.
An email I read is still shown as unread: That's deliberate: reading through Cloud Butler leaves messages unread unless you ask, for example "Read it and mark it as read."
My agent wants to do what an email says: Say no. Emails are labelled as untrusted content so agents don't follow them, but no agent is perfect. Tell us at Support so we can look at it.

Calendar and contacts

Event times are an hour or more off: Tell your agent your time zone: "I'm in Central time." Cloud Butler returns times in UTC and your agent converts them.
I changed one meeting and the whole repeating series changed: Cloud Butler edits repeating events as a whole series for now. Fix it in the Calendar app, or ask your agent to create a one-off event instead. Calendar limits.
A contact lost a phone number after an update: A new list of numbers or emails replaces the old list. Ask your agent to add the missing one back, and to include existing numbers next time.

Devices (Cloud Butler app)

"No Apple device is paired": Device features need the Cloud Butler app, which isn't released yet. When it is, pair a device.
An action says it's "still waiting": It needs your approval on one of your devices, or the device is offline. Open the Cloud Butler app and approve or decline. Actions expire after 10 minutes. Ask "Did that finish?" to check (device_get_job_result).
"Too many device actions this minute": The limit is 60 a minute. Wait a moment and try again.
"Too many pairing attempts": Wait a minute, ask for a new code and type it carefully. Codes work once and last 10 minutes.

Still stuck?

Contact support. Tell us which AI app you use, what you asked, and the exact message you saw. Never send us your Apple ID password or your app-specific password; we will never ask for them.