A calendar is empty or out of date

Read the widget's own words first

Mirra keeps three answers apart on purpose, because on a meeting-room door an empty agenda is a claim that the room is free, and a screen that says a busy room is free is worse than a screen showing an error.

• "No calendars connected — add one in the portal." — the account has no calendar connections at all.
• "Nothing coming up." — the calendars were read successfully and there is nothing inside the range the widget asked for.
• "Calendar unavailable" with "This is not a claim that nothing is booked." — the calendar could not be read. This is the message that means something is broken.
• "No room set for this screen" with "Assign a room to this screen in the portal." — a panel is asking for its own room and no room has been assigned to it. Open the screen from the dashboard and set This screen's room in the right-hand column.

The difference between the second and the third is the whole diagnosis. "Nothing coming up" is a working calendar; go to the date-range section. "Calendar unavailable" is a broken connection; go to the two sections after this one.

Check these in this order

1. Look at the Calendar page

   Integrations, then Calendar. Every connection is listed with its type and a line of detail. A calendar that is not on this list is not connected, whatever anybody remembers doing.

2. Decide which message the screen is showing

   Empty and unavailable are different faults and lead to different sections below.

3. Check what the widget was asked for

   Days ahead, Max events, and which calendar. A widget looking seven days ahead on a quiet week is correct to show nothing.

4. Wait five minutes, or reload the screen

   Calendar widgets refetch every five minutes, and iCal feeds are cached for five minutes. A change made moments ago has not necessarily arrived yet.

5. Reconnect the account or feed

   For Google and Outlook this means removing the connection and connecting again — there is no reconnect button.

An expired authorisation

Google and Outlook calendars are connected by OAuth. Mirra keeps a refresh token and quietly exchanges it for a fresh access token whenever the old one expires, which is why a working connection needs no attention for months at a time.

When that exchange fails, the calendar cannot be read at all and the widget shows Calendar unavailable. Providers refuse the exchange for reasons that have nothing to do with Mirra: a changed password, a reset of multi-factor authentication, an administrator revoking application access, or an account leaving the organisation.

There is no reconnect button, and pretending otherwise would be worse than saying so. Press Remove on the connection on the Calendar page and connect the account again from Connect an account.

• Connecting Google or Outlook again without removing the old connection leaves two connections reading the same calendar, and every event appears twice on the wall.
• "Google didn't grant offline access, so the calendar couldn't be kept in sync." during the sign-in means the consent screen was completed without offline access. Start again and accept everything asked for.
• "Google sign-in was cancelled." or the Outlook equivalent means the sign-in was declined rather than failed. Nothing was saved.

Reconnecting creates a new connection with a new identity. Any widget set to that specific calendar by name will then read Calendar unavailable until it is pointed at the new one. Widgets set to All calendars pick it up with no changes at all.

A changed password on a feed

CalDAV connections store a username and a password of their own, and unlike OAuth there is nothing to refresh. Changing the account password stops the calendar the next time Mirra reads it. Use an app-specific password rather than the account password, which is what the form suggests, and it survives an ordinary password change.

iCal feeds carry no credentials at all — the secret is in the URL. Regenerating the secret address at the provider, which many providers offer as a security measure, makes the stored URL dead. Add the feed again with the new address.

In both cases the repair is the same: remove the connection and add it again with the current details.

The wrong kind of URL

Mirra reads a feed before it saves it, so a URL that cannot work is refused at the point of adding rather than silently accepted and blank on a wall a week later. That has a useful consequence for diagnosis: if a feed was accepted once and is empty now, the URL was correct and something has changed at the other end.

• "Couldn't read that calendar — check it's a valid iCal/ICS feed." — the address is reachable but is not an iCal feed. A link to a web page showing a calendar is the usual mistake.
• "Couldn't read that CalDAV calendar. Check the collection URL and credentials." — CalDAV wants the direct collection URL, not the server root and not the web interface.
• "A valid http(s) URL is required." — the address does not start with http:// or https://.
• Google publishes one under Settings, your calendar, "Secret address in iCal format". Outlook publishes one under Calendar settings, Publish.

The CalDAV form says it works with Nextcloud, Fastmail and iCloud. Mirra asks for read-only access to calendars and never changes anything in them.

A date range with nothing in it

This is the commonest cause of an empty agenda that is not a fault at all. The widget asks for a window, and outside that window there is nothing to show however full the calendar is.

There is a second, wider limit behind it. Mirra fetches roughly six weeks back and ten weeks forward from every provider, sized for the month grid, and no widget can see beyond that. An event four months away is genuinely not on the screen yet. Each Google or Outlook account also returns at most a hundred events per fetch, which a very busy work calendar can reach.

Days ahead

How far forward the agenda looks. Set to 1 on a Friday evening it will often be empty and correct.Default: 7

Max events

The most events it will list, however many fall inside the window. A long list quietly truncated at the bottom is this setting.Default: 8

Calendar

Which calendar it reads: This screen's room, All calendars, or one named connection. A widget pinned to one connection shows only that connection.Default: All calendars

A Google connection reads that account's primary calendar. A secondary Google calendar — a shared family one, a subscribed school one — does not appear through the OAuth connection, and has to be added separately as an iCal feed.

How often it refreshes

Nothing on a wall is instant, and knowing the intervals stops you chasing a fault that is simply a wait.

Calendar widgets refetch every five minutes. Beneath them, an iCal feed is cached for five minutes per address on the server, so two screens showing the same feed do not both go and fetch it. The screen refetches its whole configuration once a minute, which is why a layout change appears quickly while the events inside it still move on the slower cycle.

Outlook connections can be faster than that. Where the installation has a public HTTPS address, Mirra subscribes to Microsoft's change notifications and a change made on a phone reaches the wall in seconds. The Calendar page says so per connection: "Connected via Microsoft — changes appear within seconds". A connection without that line is on the five-minute cycle and is working perfectly well.

An iCal feed is only as fresh as its publisher makes it. Some school and sports feeds republish hourly, and no setting in Mirra can make one arrive sooner.

Meeting-room panels

A door panel set to read this screen's room behaves differently from every other calendar widget, deliberately. If no room has been assigned it shows "No room set for this screen" and stops. It never falls back to every calendar in the building, because a corridor panel listing somebody else's meetings is worse than one admitting it does not know.

When rooms have just been set up, a correctly configured room can still read as refused for a while. Exchange caches application permissions, so allow up to two hours before re-running the configuration. The connection's own line on the Calendar page carries whatever Microsoft last said about it.