Appearance
When something is wrong
By symptom. Every refusal also carries a code, and the error reference has a section per code with what to do about it — go there first if you have one.
The client taps a heading and nothing opens
The element rendering that value has no data-jtk-path, or it has the wrong one.
This is the failure the whole annotation apparatus exists to prevent, because it is silent: the page looks right, and only the editing is broken. A build should have caught it with JTK_E_UNANNOTATED_FIELD — if it did not, the field is probably one the lint does not require an annotation for, and the reason is one of:
- its kind is one the lint advises on for now — a phone, an email, a link, a choice, a date, an hour, a number: the build log says
JTK_W_UNANNOTATED_FIELDand goes on — or is not tapped at all, a list or a switch (see field kinds); - the field is
client_editable: false, so there is no tap to break; - it is
no_tap_targetand drawn anyway — the log saysJTK_W_DRAWN_UNTAPPABLEwhere it finds the value as text; - the value is empty, and the lint only looks for annotations on values that exist.
The build fails and the log is about the schema
The schema in the repository is not the one you judged. Two common causes: it was not committed, or it was committed on another branch. Read the build log for the code and look it up.
A build with no schema at all fails with JTK_E_CATALOGUE_MISSING — the lint refuses rather than skipping, because a lint that quietly passes when it cannot find its schema is worse than no lint.
The schema was fine yesterday and is refused today
Check the contract number in the finding. A schema written for a higher contract than the service speaks is refused deliberately and completely — the service is behind, and this is a deploy rather than a repository to fix. A schema written for a lower one is upgraded silently and never produces this.
A translation is refused, or a language shows the original's words
A translation (<name>.<locale>.json beside its original) holds only words. A price, a photograph's file, a date or a link in it is refused with JTK_E_TRANSLATION_SHARED: change it in the original, or say localized: true on the field if it really differs per language. A record in translated the import cannot read is JTK_E_TRANSLATION_RECORD: leave the record out, and the import writes one. Words for a block or a row the original no longer has are advice, JTK_W_TRANSLATION_ORPHAN, shown nowhere: the key is misspelt, or the original lost the row.
A page in another language that shows the original's words is a value nobody translated yet, and the page says so with the original's lang. get_site lists each one with its file and path (a site in several languages). A service or a master shown in the original's words in every language is the rule, not a fault: what is booked is never held back.
A field exists in the schema and the admin does not draw it
The site is being served a different schema than the one in your working tree. The stored schema is a replica, pinned to the last publish — the admin draws what was published, not what is on your branch. get_registry returns the one actually in force; compare it against your file.
A site that has never published, and is not the studio's own, has no schema at all and is an error rather than a default. That is on purpose: falling back to our eleven scaffold blocks would describe a stranger's site not at all.
Publishing is refused because of enquiries
A block declares "collects": "enquiry" and the site has no verified destination. Add one — a Telegram chat, an email address, or the admin's inbox — and verify it.
The gate is derived from the schema rather than configured, so it cannot be switched off; the way out is to name a destination, or to stop collecting.
A test enquiry does not arrive
In order:
- Does a block actually declare
"collects": "enquiry"? - Is a destination verified, not merely added?
- Is the form posting to
/api/leadon the site's own host? - Is the honeypot field being filled by something? A form that fills its own hidden field is silently discarded, which is exactly what it is for.
preflight walks the whole path with a probe the edge accepts and drops; with send_real_enquiry it sends a real one the client will see, and says where it arrived.
The preview link does not work
Preview links are capability URLs with a short life. They expire, and they are credentials while they live — anybody holding one can see the preview. Mint a fresh one rather than debugging an old one.
The build log says a host was refused
JTK_E_BUILD_REACH, with the request and the list. A build has no network of its own; the platform forwards the clone, the npm and yarn registries, the media host and Google Fonts, and refuses everything else (the network). Find what asked: a dependency whose install downloads a binary from a release (pin one that ships its binaries as packages — sharp since 0.33, esbuild, lightningcss all do), a font fetched from a CDN (put the file in the repository, or use Google Fonts), a fetch to a service at build time (that content belongs in jtk/). The build is not retried on its own: fix the source and commit.
The build log says GitHub asked us to slow down
Many builds asked GitHub for repositories at once, and it answered 429. The build waits and asks again — after 5, 15 and 40 seconds, or as long as GitHub's Retry-After asks, up to a minute — and a log that goes on past those lines is a build that got its commit. One that GitHub turned away every time fails with a sentence saying so: nothing in the site is wrong, build again in a few minutes. A 5xx from GitHub is waited out the same way. A refusal (401, 403, 404) is not: check that our GitHub App is still installed on the repository.
A tool says "too many requests"
JTK_E_RATE_LIMITED, a 429 with retry_after — the seconds until there is room again, the Retry-After header too. The platform takes 9 000 requests a quarter of an hour from one account, its people in the panel and its agents together, and 1 200 from one address without a session (the error reference). Nothing was done; wait the seconds it names and the same call works. A loop is the usual cause: a get_build asked again the moment it answers, a get_site before every step. Wait a few seconds between polls.
The build says a file was not published
not published: .env, … in the log, withheld on get_build, and preflight failing nothing in the build that is never published. A path with a part that starts with a dot — .env, .env.backup, .git/, img/.DS_Store — is never served, .well-known/ at the root aside: the upload leaves it out and the address answers 404. The build still succeeds. But the file came from the repository, usually from public/, so it is in the repository's history. Remove it there and commit; if it held a key, a token or a password, change that secret too, because deleting the file does not take it out of the history.
A rollback keeps undoing itself
It does not: the rollback holds the site on the build it chose, and only a person lifting the hold in the panel, and then publishing, moves it on. A build of a newer commit lands as the candidate meanwhile, with JTK_E_PUBLISH_HELD in its log. The artefact and the repository disagree until the source is fixed — see draft, version, live.
The site answers 503 and the panel says it is switched off
Either the studio switched it off (The site → Switch off, with a reason only the studio sees) or the lapse ladder did, on day 30 of an unpaid subscription — the reason then reads lapsed: …. The first comes back with a press; the second the moment the subscription is paid, within the minute. The panel has both ladders.
Editing is refused with "this site is frozen"
Day 14 of the lapse ladder: reading and export work, writing does not. Two sentences, two payers. Its subscription has not been paid is the studio's plan with us, under Reselling. The payment to the studio that runs it is overdue is the owner's invoice to the studio, paid from the owner's Subscription screen. Paying thaws; nothing else does.
Launching is refused: "needs one site in this studio's plan"
The plan is short by one line of the kind named — a site, a diary or a shop. Reselling sells one more; a site costs nothing until then, so this arrives on the day the site goes live rather than before. The same sentence refuses turning the diary or the shop on for one more site and billing one more client.
A visitor cannot book, and the diary says what is missing
Two halves, and the sentence names which. This site's schema does not turn bookings on is the repository's — modules.bookings and its two collections, then commit, import, build. Nobody has said which timezone this business keeps / when this business is open is the owner's — Diary → Opening hours, then save and publish. Nothing in the services collection says how long it takes is an entry without takes; the resources collection has nothing published in it is nobody to book with. preflight says all of them.
A buyer cannot buy, and the shop says what is missing
Two halves again, and what a buyer is told names which. A product sold out that never sold is a counted product nobody stocked: set_stock sets the count, or the product says tracked: false where it is made to order. No way to send it is the shop's settings — a country no zone names (sends is false in the shipping answer), a method no parcel of this size or weight fits (cannot_send), or a method with no price yet, which is a draft that preflight names; a pick-up is offered whatever the country. A checkout refused with 424 no_payee is the business without a Stripe account to be paid into, which a person connects under Payments — or, on a launched site, a studio's plan that holds no shop line for it, which Reselling sells and the site's next publish takes; the cart is still priced and an order already made still answered, and only a new order waits; 422 address is Stripe unable to work out the VAT for the delivery's address, and the buyer checks it. A page whose button does nothing has lost a hook — the element says in the browser's console which — and a cart or a checkout field the page sent that the contract has not got is dropped for a stranger and listed in get_site's shop_drops (JTK_E_SHOP_FIELD_UNKNOWN to a preview). preflight with try_order walks the shop's addresses as a buyer does, not the page's hooks, which the element and jtk a11y find (the shop on the site).
Payments cannot be set up: "say what country this business is in"
The country lives on The site → The business and is the first thing a Stripe account needs. A country Stripe does not serve is refused by name, and there is no second provider today. The same is true of a studio's own account under Reselling, for billing its clients.
Client billing refuses to start
The studio's own payment account is not ready yet — set it up under Reselling → Stripe account, then wait for Stripe to say it may charge. The price… belong to the running subscription — stop it and start a new one; a running subscription is never silently resold.
The handover is refused
Every reason at once, in one sentence. The enquiries still go to an address somebody set up here — the owner adds their own destination and the studio's is removed. The money from this site still lands in the account somebody set up here — the site's Stripe account for bookings is the studio's; remove it. The owner still pays this studio for the site through us — stop that subscription first, or the client is billed twice. Fix each, then mint the link again.
Still stuck
Get the code. Every judge in the system — the schema validator, the annotation lint, jtakeit doctor — says the same code for the same fault, and the reference has one line of what to do for every one of them. A symptom without a code is worth reporting as a gap.