Trust and help

Troubleshooting

Fixes for the problems people meet most with Brunel. Repositories not found, limits, sign-in, API keys, MCP clients, webhooks and deployment pull requests.

"Repository not found"

Check the address: only GitHub is supported (owner/repo works).
Private repository: sign in, check your plan includes private repositories, and that your GitHub account can read it. For an organization, install the Brunel GitHub App on that repository (Missing an organization? in the picker).

"Repository too large" or "too many files"

Brunel keeps up to 150 MB of code and configuration and 20,000 files. Point Brunel at the branch you deploy; large generated folders committed by mistake count against the limit.

"Upgrade required" (402)

A plan feature or monthly quota. Platform → Overview shows usage against quotas. See Plans and limits.

The action needs a sign-in from the last two hours. Choose Sign in again: you come back to the same page, including on console addresses.

"This console link has expired"

Console sign-in links work once, for 60 seconds, in the browser that opened them. Open the page again from https://brunel.cloud.

API key refused

Code	Fix
`auth_required`	Send `Authorization: Bearer <key>`
`invalid_api_key`	The key was revoked, expired, or rotated past its grace period
`read_only_key`	Use a `brn_w_` key for writes
`ip_not_allowed`	Add this address to the key's allowed IPs
`policy_denied`	Your team's IP allowlist refuses this address

MCP client does not see the tools

The URL is https://api.brunel.cloud/mcp, transport HTTP (Streamable HTTP), not SSE.
The header is exactly Authorization: Bearer brn_….
Restart the client after editing its configuration. Claude Desktop needs Node.js for mcp-remote.

Webhook deliveries fail

The endpoint must be a public HTTPS address and answer 2xx within 5 seconds; redirects are not followed.
Verify the signature on the raw body before parsing.
Open the delivery in Platform → Webhooks to see the response code, then Redeliver.

Deployment pull request without a workflow

Your GitHub token cannot write workflow files; the workflow is in infra/workflows/. Move it to .github/workflows/, or sign in again granting the workflow scope.