Troubleshooting

Sign up rejected

• Username must be 6–32 characters, lowercase letters, digits, underscore. No dash.
• Email already registered, or username taken.
• Terms checkbox must be on.

Empty journal after create

• You created an Empty Git repo and have not pushed main.bean.
• Sample create is still running. Refresh My Repositories.
• Date filter excludes every entry. Clear Add filter.

Push rejected / website commit failed

• Missing main.bean at the repo root.
• include of a file that is not in the tree.
• Beancount error (unbalanced transaction, unknown account). Read the error Git printed, or the red banner on the website.
• Entry quota. Settings shows entry_count / quota. Upgrade or make the book public (only if you accept public data).

Import did nothing

• .beanhub/imports.yaml missing or inputs: [].
• CSV path does not match inputs.match (example: rules expect import-data/mercury/*.csv but you uploaded another name).
• Extractor mismatch (extractor: mercury vs a Plaid CSV).
• Rows are in Open TXNs, not the journal. That page is unmatched bank rows. Click Add or write a rule.

Connect Bank missing or errors

• Free plan: Connect is unavailable. Upgrade or use CSV upload.
• Country not supported: modal “Unsupported bank country”.
• Plaid window blocked by a browser popup blocker.
• Quota: “Your plan only allows N connected banks across your account”.

Inbox empty

• Nothing forwarded yet.
• Wrong address. Must be username+reponame@inbox.beanhub.io.
• Pause Inbox Receiving is checked in repository Settings.
• You are on a local/dev app without the inbound mail pipeline.

API 401

• Send Authorization: Bearer YOUR_TOKEN. The access-token header still works and is deprecated.
• Token deleted, wrong scope, or missing grant.
• An MCP OAuth token does not unlock the HTTP API. A CLI access token does not unlock MCP.

MCP connection failed

• The AI app must use https://api.beanhub.io/mcp. https://app.beanhub.io/mcp/ is MCP settings in the website, not the server.
• MCP is off until you enable it under MCP settings. See Connect an AI app with MCP.
• Do not send a CLI access token to MCP. Hosted MCP uses OAuth. A CLI token as Authorization: Bearer is for the HTTP API, not MCP.
• Paused on the connected-app row returns an error that the connection is paused. Turn Paused off to resume.
• Read-only grants hide write tools. Turn Allow updates on if the app should change the book.
• ChatGPT needs developer mode on a Plus, Pro, Business, Enterprise, or Education plan. The toggle lives under Settings. If it is missing, the plan or workspace does not include custom MCP.

Git authentication failed

• Password must be the token, not the account password (unless you still use the legacy password path; prefer a token).
• Token lacks Git HTTP read/write.
• Clone URL must be /repos/<username>/<repo>.git on app.beanhub.io.

Clone 404

• Wrong username or repo name.
• Token scope is Selected Repositories and this book is not on the list.
• Connect-only repo has no Git remote.

Still stuck: support@beanhub.io.