Troubleshooting

Most problems fall into a handful of categories, and the error Black Hole shows you is the real one from the underlying service. Reading it carefully usually points straight at the fix. This page covers the cases that come up most often.

A build stopped with a red step

The failing step names what went wrong. There are four common causes and they have different fixes:

• Rejected credentials. The provider refused the key. Check it is still active in the provider's dashboard and that billing is set up on that account.
• Rate limited. Your provider is throttling requests. Wait a minute and try again, or raise the limit on your provider account.
• Quota or spend limit reached. Your provider stopped serving requests because a cap was hit. Raise the cap or wait for the period to reset.
• The model returned something unusable. Rare, and usually fixed by simply sending the request again or switching to a stronger model.

My API key will not save

1. Check you picked the right provider — an OpenAI key will not verify against Anthropic.
2. Copy the key again; a trailing space or a truncated paste is the most common cause.
3. Confirm the key is active and not revoked in the provider's dashboard.
4. Confirm the account has billing enabled — many providers issue keys that cannot call anything until a payment method exists.
5. For a custom endpoint, check the base URL and that the API format matches what your server actually speaks.

Black Hole verifies keys with a real call, so the message you see is the provider's own response. If it says the key is invalid, the provider is saying that, not Black Hole.

I cannot sign in

Wrong password

Use the forgotten-password link to receive a reset email. Check the spam folder if it does not arrive within a couple of minutes.

Two-factor code refused

Authenticator codes depend on the clock. If your phone's time is even slightly off, codes fail. Turn on automatic time in your phone's settings. If you have lost the device entirely, use one of the recovery codes you saved when enabling two-factor.

Temporarily blocked

Repeated failed attempts block a network for a period. Wait for the stated time; the block clears on its own.

Face or fingerprint sign-in will not start

• It only works on a secure connection — an https address, or localhost during development.
• It is blocked inside embedded preview frames. Open the page in its own browser tab.
• The device must actually have a scanner set up at the operating-system level.
• If none of that applies, use the two-factor code fallback shown on the same screen.

The preview is blank or looks broken

1. Wait for the build to finish — the preview only fills in once files exist.
2. Reload the page; a stale preview frame occasionally needs a refresh.
3. If a step failed, fix that first — a half-written build renders as a blank or partial page.
4. Ask the agent directly: "the preview is blank, check the page for errors".

Publishing problems

• Changes are not showing. Publishing is a deliberate step. Edits stay private until you press Publish again.
• The live site differs from the preview. You are seeing the last published version. Republish to bring them in line.
• A custom domain is not resolving. DNS changes take time to spread and are configured at your registrar, not in Black Hole. See Publishing and GitHub.

GitHub sync errors

• Reconnect GitHub if the authorisation was revoked or expired.
• Confirm your account can write to the repository you selected.
• If a push is rejected, pull first — the repository has changes Black Hole does not have yet.

Still stuck

Note the exact wording of the error, what you did immediately before it, and which model or key you were using, then get in touch through the address on the about page. Those three details resolve most reports on the first reply.