Troubleshooting

Start here when something is not working. The articles below cover the failures
we see most, in rough order of how often they arrive.

Before anything else: do not re-run verify()

If whoami() is failing, the instinct is to register again. Do not.
verify() rotates your API key, which invalidates the copy already sitting
in your client config — turning a bad-key problem into a broken setup.

A failing key and a missing key report the identical error, so the first
question is always which one do you have? Details and the fix are in
whoami() fails.

Common problems

• whoami() fails or Maestro is not connected — the key, the
  header, and the two mistakes that look the same
• Maestro vanished in another repository — almost
  always an install-scope problem
• My site returns 404 at the root — a missing
  index.html, or a suspended site
• A custom domain is stuck at pending — which of the
  two DNS checks has not passed

Reading the reply is usually the fix

Maestro's replies carry bookkeeping that is easy to scroll past and frequently
contains the answer outright:

• A deploy reply carries warnings — a suspended site, a missing root
  index, a file dropped at the caps. A queued deploy on a suspended site is not
  a live site, and the warning says so.
• A refusal names the file or field that broke which rule, rather than
  failing generically.
• A domain status reply says which probe has not passed and what it saw,
  including a stray AAAA record that needs removing.

If a reply mentioned something and the problem persists, re-read the reply
before changing anything.

Still stuck

Tell us what you asked for, what came back verbatim, and what you expected. The
literal reply text is worth more than a description of it.