> ## Documentation Index
> Fetch the complete documentation index at: https://pomeroy.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Every way Pomeroy can appear not to work, and the fix: missing tools, an app switched off, the weekly allowance, weather, updates and permissions.

Start here. Almost everything falls into one of the first three sections.

## An assistant cannot see the tools

The most common problem, and almost always the least interesting cause.

<Steps>
  <Step title="Restart the assistant, properly">
    Most assistants read their server list at launch. Quit it fully and open it
    again; on a Mac that means **Quit**, not closing the window. Claude Code
    and goose need a **new session** rather than a restart.

    [Which assistants need what](/docs/configuration/overview#after-setup)
  </Step>

  <Step title="Check Pomeroy is running">
    Look for the tree icon in your menu bar. If it is missing, open Pomeroy from
    Applications.

    Pomeroy does not need to be running for a tool call to work, because the
    pipe launches it. But if it will not start, nothing else will either.
  </Step>

  <Step title="Check the assistant is actually configured">
    Open the Pomeroy panel and look at your assistant's row. If it does not show
    as set up, press **Set up** again; it is safe to run any number of times.
  </Step>

  <Step title="Check the path">
    If your assistant reports that the server failed to start, it could not run
    the command. The path must match where Pomeroy actually lives:

    ```
    /Applications/Pomeroy.app/Contents/MacOS/pomeroy-mcp
    ```

    Keeping Pomeroy somewhere else changes it. The Pomeroy panel always shows
    the right one for your Mac, so copy it from there.
  </Step>
</Steps>

## An app is switched off in Pomeroy

This is not an error. It is Pomeroy working: you asked about an app whose
toggle is off, and the refusal was returned instead of your data.

Click the menu-bar icon, choose **Settings**, switch the app on, and ask again.
No restart is needed. The tool list has not changed, only whether the call
gets through.

If macOS then asks for permission, that is the grant being requested for the
first time. [Toggles and grants are two different
things](/docs/getting-started/permissions).

## The weekly allowance ran out

Every tool answers with a message saying the allowance is used up and when it
refills. Nothing is broken and nothing is lost.

* Checking is always free: ask **"how much of my Pomeroy allowance is left?"**
* The count refills a week after the current window started.
* \$19 once removes the limit. [Buy and activate](/docs/licence/buy-and-activate)

Changing your Mac's date will not refill it: the meter uses a clock that no
setting can move. [Why](/docs/licence/free-allowance#why-the-clock-cannot-be-cheated)

## An app returns nothing, or an error

<AccordionGroup>
  <Accordion title="Mail: a content search finds nothing" icon="envelope">
    Body search runs against an index Pomeroy builds on your Mac, and the first
    build takes a while on a large mailbox. Every content answer says how much
    of your mail the index covered and how old it is, so "nothing found" may
    mean "nothing in the part indexed so far".

    Ask the assistant to build the mail index, wait for it, and search again.
    [How the index works](/docs/apps/mail#the-content-index)
  </Accordion>

  <Accordion title="Weather returns nothing at all" icon="cloud-sun">
    WeatherKit checks the app's signature against a paid Apple developer team,
    and refuses builds it does not recognise. A release from pomeroy.app is
    signed; a local build is not.

    There is deliberately no third-party fallback. One would send your questions
    somewhere the pledge page does not name.
    [Why](/docs/apps/weather#the-one-request-that-leaves-your-mac)
  </Accordion>

  <Accordion title="Messages: a new message is missing" icon="comment-dots">
    Pomeroy reads the database the Messages app writes to. A message it has only
    just written can take a moment to appear. Wait and ask again.
  </Accordion>

  <Accordion title="Messages: it says it cannot read the database" icon="database">
    The read-only bookmark to `chat.db` has been lost, usually after a macOS
    upgrade or a migration. Switch Messages off and on again in **Settings**,
    and hand over the file when the dialog opens.

    Pomeroy proves this grant by resolving the bookmark and opening the file
    each time, rather than remembering that you once granted it. That is why it
    notices.
  </Accordion>

  <Accordion title="Shortcuts: it says the name did not match" icon="wand-magic-sparkles">
    `shortcuts_run` needs the name character for character. A near miss runs
    nothing and lists the candidates instead of guessing. Pick the exact one
    from that list.
  </Accordion>

  <Accordion title="Calendar or Reminders: permission was granted but it still fails" icon="calendar">
    On recent macOS, agreeing to the prompt is not sufficient on its own. The
    app also needs a matching entitlement, and a build without one is refused
    even after you say yes. A release from pomeroy.app has them. [The five
    entitlements](/docs/privacy/what-pomeroy-asks-macos-for#the-entitlements-that-go-with-them)
  </Accordion>
</AccordionGroup>

## Permissions

<AccordionGroup>
  <Accordion title="macOS never asked me for permission" icon="bell-slash">
    Pomeroy asks only at the moment you switch an app on, and only for that app.
    If you have already answered once, macOS does not ask again. Check **System
    Settings → Privacy & Security** for the current answer.

    Maps and Weather never prompt: MapKit and WeatherKit answer any app, so the
    toggle is the whole gate.
  </Accordion>

  <Accordion title="I said no and want to change my mind" icon="rotate-left">
    macOS owns that answer. Open **System Settings → Privacy & Security**, find
    the relevant list, and allow Pomeroy. Pomeroy reads grants live and never
    caches them, so it notices immediately.
  </Accordion>

  <Accordion title="I was asked three times for Mail, Notes and Shortcuts" icon="list-check">
    Correct. Automation is asked for per app, so approving Mail says nothing
    about Notes.
  </Accordion>

  <Accordion title="Pomeroy is not in the Accessibility list" icon="circle-check">
    It never will be. Accessibility and Screen Recording are the two grants
    Pomeroy will never ask for, and its absence from those lists is something
    you can verify in five seconds.
    [Why](/docs/privacy/what-pomeroy-asks-macos-for#what-pomeroy-will-never-ask-for)
  </Accordion>
</AccordionGroup>

## Updates and the app itself

<AccordionGroup>
  <Accordion title="macOS says Pomeroy cannot be opened" icon="lock">
    Pomeroy is signed and notarised by Apple, so this usually means the download
    did not finish. Delete it and [download it
    again](https://pomeroy.app/download).
  </Accordion>

  <Accordion title="Updates are not arriving" icon="arrows-rotate">
    Check **Settings → General → Keep Pomeroy up to date**. If it is off,
    Pomeroy never asks, which is the switch working as intended.

    Every update is signed, and one whose signature does not match the bytes is
    thrown away rather than installed.
  </Accordion>

  <Accordion title="The Claude extension disappeared" icon="puzzle-piece">
    Claude Desktop occasionally loses an extension after a major update. Press
    **Set up** in the Pomeroy panel again. It is safe to run any number of
    times. [Setting up Claude Desktop](/docs/assistants/claude-desktop)
  </Accordion>
</AccordionGroup>

## Still stuck

Email [hello@pomeroy.app](mailto:hello@pomeroy.app). Saying which assistant,
which app, and what the assistant reported back gets to an answer fastest.