Troubleshooting

What goes wrong when a site is set up and run with Heddle, how to tell, and what to do. Each entry happened on one of our own sites; the date says when.

Email

Mail from a new domain never arrives

Why. A brand-new sending domain looks like phishing to a company's mail filter. Microsoft Defender quarantined short test emails from a new domain as "Phish", sent straight to an executive's mailbox, while the contact form's mail to a shared inbox got through (October 2026).

Tell. Plunk still reports quarantined mail as Delivered, and the scanner's link check shows as Opened and Clicked. Look in the quarantine; Plunk cannot see it.

Fix. In Microsoft Defender: Email and collaboration, Review, Quarantine. Select the domain's messages, Submit to Microsoft for review, "should not have been blocked", Allow this message with "45 days after last used date", then Release. An allow entry for a sending domain can only be made from a submission. Test with a real notification.

A one-line "test" with a single link scores as phish on its own.

Cloudflare Email Routing will not enable

Why. Plunk offers an inbound MX record at the bare domain (inbound-smtp.<region>.amazonaws.com) for receiving mail into Plunk. Sending does not need it, and while it exists Email Routing refuses to enable: "Existing non-Cloudflare MX records conflict with Email Routing", or the Activate button appears to do nothing (October 2026).

Fix. Delete that one record, keep the MX on the plunk. subdomain, and enable Email Routing again. heddle launch names the record when it finds it.

Enabling Email Routing from the API is refused

Why. The enable call needs Zone Settings at Edit; Read is not enough (October 2026).

Fix. Give the launch token Zone Settings: Edit, then rerun heddle launch <site> --apply.

Cloudflare

A Worker cannot fetch a page on its own domain

Why. A Worker that requests a URL on the zone it serves gets a 522 from Cloudflare instead of the page. The free tools on one of our sites tried to read the site's own files over the network and failed (October 2026).

Fix. Read the site's own files from the Worker's static-assets binding instead of fetching them, and fetch over the network only for other hosts.

A new file answers 404 just after a deploy

Why. New assets can take a few seconds to reach every location after a deploy (September 2026).

Fix. Probe again before concluding the file was not shipped.

A merged change is not live

Why. A merge does not deploy anything by itself. A merged change was not live and a link in an outbound email answered 404 (September 2026).

Fix. Deploy is its own step. To verify a deploy, probe for a string only the new build contains. A 200 alone proves nothing.

The new domain does not resolve after cutover

Why. Your machine's resolver can cache "not found" for the domain for minutes after the custom domain is attached (October 2026).

Fix. Test with curl --resolve <domain>:443:<ip>, taking the ip from dig @1.1.1.1 <domain>, before suspecting the deploy.

The agents still read the preview after cutover

Why. The agents read HEDDLE_SITE_URL until it is removed (October 2026).

Fix. Delete the repository variable (gh variable delete HEDDLE_SITE_URL -R <owner>/<site>) and set autonomy.json runtime.leads.url to the live domain.

_headers rules past the hundredth are ignored

Why. Cloudflare reads at most 100 rules from _headers and drops the rest without a word. One Link rule per page reached 87 rules at 81 pages on one of our sites (October 2026).

Fix. heddle aeo refuses to write past the limit. Past about 80 pages, set site.json agentReady.linkHeaders to "runtime" and announce the Markdown twins from the Worker.

Indexing

IndexNow answers 403 SiteVerificationNotCompleted

Why. It is the normal first answer while the search engines fetch and verify the key file (October 2026).

Fix. Wait, then run heddle indexing submit <site> again. The key file must be deployed before the first submission.

A page dropped out of results and nobody noticed

Why. A page went unrecrawled for four weeks after it changed (October 2026).

Fix. Each SEO agent pass inspects the newest pages. One crawled more than three weeks before its last change goes on the indexing list and back to IndexNow. You can inspect one yourself with heddle research <site> gsc inspect <path>.

Data and models

DataForSEO fails as if the password were wrong

Why. The account is prepaid, and an empty balance answers like a bad key (September 2026).

Fix. heddle research <site> balance before changing the credentials.

The AI Gateway answers 402

Why. The gateway's credits have run out, and the token itself is fine (October 2026).

Fix. Add credits to the gateway. Keep automatic top-up off and let autonomy.json budget.floorUsd stop the agents before it runs dry.

Model checks say SKIPPED

Why. The judging model's token or account variable is not set. A skipped check is not a pass, and in CI heddle check fails on it.

Fix. Set the variables site.json model names. Pass --offline only when you mean to skip the model checks.

A new secret stopped another one working

Why. A line appended to a secrets file with no final newline glued onto the secret before it, and both stopped working (October 2026).

Fix. Check that the file ends with a newline before appending to it.

GitHub

The agents' workflow cannot read Heddle

Why. Some organisations disable deploy keys, so a read-only deploy key on the Heddle repository cannot be added (October 2026).

Fix. Use a fine-grained token with Contents read-only on the Heddle repository as the HEDDLE_REPO_TOKEN secret.

A daily agent ran twice

Why. A doubled schedule or a retried run would open the same pull requests and send the same emails again (October 2026).

Fix. There is nothing to do. A pass that already succeeded inside its schedule does nothing, and an email is recorded as sending before it is sent. heddle agent <id> <site> --force runs it anyway.