Troubleshooting

Common problems and how to fix them.

API key problems

"Your API key isn't working"

This means Margaret tried to use your key and Anthropic rejected it. The most common causes:

The key was entered incorrectly. Go to Settings → API key → and re-enter it. Make sure there are no spaces at the start or end. API keys start with sk-ant-.

The key has been revoked. If you deleted the key from the Anthropic console, it won't work any more. Go to console.anthropic.com → API Keys and create a new one.

Your Anthropic account has no credit. If your balance is zero, API calls will be rejected. Go to the Anthropic console → Billing and add credit.

"Can't reach Anthropic's servers"

Margaret can't connect to Anthropic. Check:

Your internet connection is working
You're not on a network that blocks external API calls (some corporate networks do this)
Anthropic's status page — if there's an outage, wait and try again

Running helpers

"Claude is very busy right now"

Anthropic occasionally rate-limits API usage during high-demand periods. Wait 30–60 seconds and try again. This is temporary and not related to your account.

"You've hit Claude's usage limit"

You've sent too many requests in a short period. This is a rate limit from Anthropic based on your account tier. Wait a minute and try again. If you're hitting this regularly, you can apply for a higher rate limit in the Anthropic console.

"Your input is too long for this model"

Every model has a limit on how much text it can process in a single request. If you've pasted a very long document, try:

Switching to Opus 4.7 — it has the largest context window (1 million tokens, roughly 750,000 words)
Shortening your input — if you only need part of the document, paste the relevant section
Splitting the task — process the document in chunks using separate runs

The output looks wrong or unhelpful

This is usually an instructions problem, not a technical problem. Try:

Tune up the helper — open Tune up and describe what's wrong. Margaret can often fix it with a targeted change to the Process section.
Check the Output Format — if the helper is producing the wrong structure, the Output Format section may be too vague. Add specific headings.
Try a better model — if you're using Haiku for a task that requires judgement, switch to Sonnet. See Choosing a model.

Helpers and files

Margaret loads helpers from your helpers folder on startup. If you added a file after opening the app, it won't appear until you relaunch.

Also check:

The file is in the top level of your helpers folder (not in a subfolder)
The file ends in .md
The filename doesn't start with a number like 00_ or 01_ — Margaret skips files with those prefixes (they're reserved for system files)

A helper appears but looks empty

Open the helper file in a text editor and check its contents. Margaret expects helpers to have a # Heading at the top and ## Section headings for each section. If the file is blank or uses a different format, Margaret won't have much to show.

My helpers folder is in the wrong place

Go to Settings → Helpers folder → Change folder and point Margaret at the right location. If your helpers are in the old folder, copy the .md files across manually — Margaret won't move them automatically.

Workflows

"Workflow references missing helpers"

One or more helpers referenced in the workflow have been renamed or deleted. Either:

Rename the missing helper back to its original name
Or edit the workflow file (it's a .yml file in your helpers folder) and update the helper name to match what it's called now

A workflow step failed but the others were fine

Each step runs independently. If step 2 fails, steps 1 and 3 are unaffected. The error message on the failed step will give you a reason — most commonly it's the same causes as a regular helper run failing (see above).

Still stuck?

If something isn't covered here, you can reach us at help@meetmargaret.com.

← PreviousPrivacy and data