Fix guides
Fix guides for the specific problems Docket reports. Each one explains what the issue costs you, then gives the change to make.
Before any individual guide, the question that decides whether an audit is worth anything: what do you do first? A list of 99 checks against a real site produces dozens of findings, and the order you work them in matters more than any single fix.
The order to fix things in
Docket ranks every finding by the same formula, and it is worth knowing because you can apply it by hand to any tool's output:
priority = severity x impact x reach / effort
x1.5 if the finding is on a page that sellsThree of those are obvious. The fourth is where most tools go wrong: reach grows
sub-linearly in the number of pages affected — a capped square root rather than a raw
count. Without that damping, a trivial nit on every page of a large site outranks a
noindex on your homepage, and the report becomes a list you scroll past. Sorting
by "number of pages affected", which is the default in several crawlers, is exactly that
failure.
In practice this collapses to a short rule. Fix anything that stops a page being indexed at all, first and immediately — those are rare and they are absolute. Then work down by priority, which naturally puts small changes on important pages above large changes on unimportant ones. A finding marked TRIVIAL or SMALL effort with HIGH severity is almost always the best hour you will spend.
What a fix guide here will not do
None of these say "improve your content" or "build quality links". If a guide cannot name the exact element to change, it has not earned the page. Where a change depends on something only you know — whether you want AI engines training on your writing, for instance — the guide sets out the decision rather than making it for you.
Fix AI crawler access in robots.txt
How to let ChatGPT, Perplexity and Claude read your site without giving away training data — they are separate decisions and need separate rules. Measured against 6236 sites' robots.txt files, most people who block AI crawlers get this wrong in the same direction.
Redirecting http:// to https://
The 301 every host configures differently, and the certificate state that makes the "Enforce HTTPS" setting refuse to turn on — written from our own site failing this exact check. How to redirect http:// to https:// →
hreflang return tags
The only common SEO tag that cannot be checked by reading the page it sits on: a declaration that goes one way is ignored entirely, and every tag looks correct in isolation. How to fix hreflang return tags →
Invalid hreflang codes
A separate failure from the one above: the tag is present and points both ways, but the value inside it is not a language code anyone recognises. What the check really validates — and the region codes it waves through. What is actually checked →
hreflang and html lang mismatch
The tag people confuse with the one above. hreflang tells search engines which
translation to serve; html lang declares what this page is written in, and only one of
them is usually wrong.
Which one you have →
Conflicting canonical tags
Two canonicals on one page, a canonical pointing at a noindex page, and the section-wide mistake that can cost a site its entire long tail while every page still returns 200. How to fix conflicting canonicals →
The social links that are not yours
A wrong sameAs entry is worse than a missing one: it asserts that your company and
somebody else are the same thing. Why a permalink is not a profile, and why repetition tells you
what your footer owns when position cannot.
What it must not claim →
A rate limit is not a block
An audit is traffic, and a crawl can trip the very rate limit it then measures. How to tell a throttle from a refusal, the one-click test that says whether a 403 is about your identity or your network, and why a re-run is the only thing that makes the finding real. Tell a wait from a refusal →
The number badged on a finding
It feeds the score and decides where the finding sits in your plan, so a count of the wrong thing moves work you do not need to do above work you do. Two cases where the badge argued with its own headline, and the four questions that catch it. Check the count →
When the form is the call to action
A page whose whole content is a quote form can be reported as having nothing to click, because the tool was looking for buttons. Why a form counts, why a search box must not, and the general fault behind half the findings phrased as an absence. Why a form counts →
What your markup says you are called
Nothing tells an audit your company's name, so it infers one — and four ordinary sites broke that inference, including a logo link whose correct accessibility label was read as a brand and then advised away. Where the guess comes from →
Reviews you do not have
An audit cannot see your reviews, so it matches phrases — and a phrase can mean two things. A site's own sentence saying it has no testimonials, counted as proof that it does; why one of these two errors is much worse than the other. Read the evidence first →
The pages an audit could not reach
Four different causes come out as one line telling you to check DNS and TLS — and on a domain that served the rest of the crawl, DNS and TLS are the one place nothing is wrong. Four questions that tell slow from down in a minute. Before you touch DNS →
The fix that deletes the evidence
"Regenerate your sitemap" is right for a 404 and wrong for four other causes — and on one site following it would have removed the only list pointing at a server fault. Why a subtractive remedy needs a higher standard of proof. Before you regenerate →
When the finding concedes your case and fires anyway
Nearly every page an insurer was warned about was a confirmation page doing exactly the right thing — and the warning's own advice said so. When an exception belongs in the rule, and when a stated caveat is the honest answer instead. Read the fix text first →
Identical content that is not duplicate content
Pages share a body for three reasons and only one of them is duplicate content. The case where following the advice would have redirected a site's blog, press page and FAQs into a terms page — and the two-minute check that tells them apart. Check before you redirect →
When a finished page is called unfinished
A charity's housing policy was flagged for discussing homes under construction, and a wiki for documenting the filler template it ships. Why both repairs replaced a question about meaning with a question about the shape of the text. Read the quoted sentence →
The schema reference that resolves to nothing
Two blocks sharing an @id are one node, so a reference carries no properties on
purpose — and an audit reading it as a half-finished entity is wrong. But a pointer whose target
is not on the same page produces neither a rich result nor an error, which is why nothing catches
it. Check the graph first →
What the JSON-LD error actually says
A check that finds invalid markup has just parsed it and caught the exact reason — then prints a list of likely causes instead. What each parser message means, and why a report can be right that they all fail the same way while the pages stay broken. Read the message →
Which host is that finding about?
A certificate warning you can disprove in ten seconds is one you stop investigating — and the finding was right about a host you did not check. Why www and the bare domain are separate configurations, and the three things "http is still reachable" can mean. Find the host first →
The hreflang target that is not really dead
Four reasons a target gets called broken, and on two of them the tool learned nothing. Plus the redirect test that could only fire on sites already doing it right — and why that is worse than a test that never fires at all. Read the reason, not the headline →
"You have no analytics" is a claim about a list
A tag in the HTML is evidence that a tag is in the HTML — nothing more. Two cases where a site was measuring the whole time and was told it was not, and why a tag container turns "you have none" into "this could not tell". Check what it named →
When the numbers add up to more than your site
Two findings, one check, the same fix, overlapping pages — and a total larger than the crawl. What a tool split that should not have been split, and why an explanation attached to the wrong condition is invisible to the people who need it. Add the counts first →
When the markup is about somebody else
A reader that walks your structured data to any depth cannot tell whose business it just found — and one property settles it. Why a marketplace was told its own address, hours and price range were missing when every fact belonged to a shop it listed. Whose data is it? →
The type you declare is a claim
A university is not a LocalBusiness in schema.org's hierarchy, so "add LocalBusiness or a subtype" offered it plumber and dentist. And a pasteable block that carries your real domain will carry somebody else's address just as confidently. Check every value →
When a field is there and still missing
You search your own markup for the property a report called missing, and find it — holding an empty value, which a search engine reads as nothing at all. The other half: the phone number reported missing because the check read one of the two places it can live. Tell the two apart →
Where a tool looks for your address
Strip the page furniture and you strip the footer, which is where a business puts its address — so the most semantic markup got the false positive. Then reading everything turned one address, published identically, into dozens of variations. Both failures, one cause →
When a pixel is on part of the site and on no pages
The inventory of your tags and the count of pages carrying them were read from different documents, so anything loaded by JavaScript was reported as a deployment gap — and a script-weight warning could never fire for the sites it was written for. What the count measures →
When the missing fields belong to the wrong type
A completeness check never judges the type you declared, so a company's identity markup labelled as a product was told to add an image — correct for the type, and worth nothing. Plus the property that was present all along under one capital letter. Read the type first →
When a dead crawler rule costs nothing
A retired crawler name in robots.txt is easy to spot and tells you nothing about what it cost — a crawler matching no group falls back to the catch-all, which is often stricter than the group written for it. How to tell an inert line from a real exposure. Read the other group →
When a report calls your decision a defect
A deliberate policy and an accident look identical in a configuration file, and a tool that cannot tell them apart will shout at one and stay quiet about the other. Plus the universal claim that was false about the reader's own file, and why it was the sentence that set the severity. Named, or caught →
When a check cannot see the markup you wrote
Schema types inherit, so a specific business type is an Organization — and a check comparing type names misses every subtype. The finding that fires hardest on whoever marked their business up most precisely, and how to tell two checks disagreeing from two checks overlapping. Look at the type first →
The fix that hid a real problem somewhere else
A guard added to stop one false positive made the same check unable to flag a genuine disagreement on another site — and a false negative makes no noise. What the narrower condition was, and what the trade cost. What a fix costs →
Not every address on your site is yours
Example addresses in your documentation, and a share button with no recipient, both look like published contact channels to a checker. What it can tell about an address, what it cannot, and why one of these was right about the defect and impossible about the repair. Whose domain is it →
When a report says nothing at all
Checks sort responses into categories, and a status that fits none of them produces no finding anywhere — not a zero, not an unclassified row, nothing. How that gap was found, why nobody reports one, and how to work out what your own report is not telling you. Find the gap →
Telling your site's furniture from its content
Counting links measures your template, not your page — and the fix for that walked into the same confusion a fifth time, excusing an empty stub as an index. The three tests that separate a navigation label from a real entry, and where each one fails. Three discriminators →
When a finding blames the whole site
Most findings count pages, but the fault was decided once in a template — so the count is the number of pages that template produced. How to find the grouping, why a majority is not a site, and the case where this tool got it wrong. Read it by the right unit →
When the site sounds like several companies
Sentence length across your pages is a crude proxy for one voice, and it works better than it deserves to. What it can see, why several voices are often correct, and why rewriting everything to one length is a metronome rather than a voice. What it refuses to judge →
When the site stops saying one thing
Read one page and it is fine; read twenty and you cannot say what the company does. The defect does not live on a page, it lives between them — and you get there by shipping good pages one at a time, not by being careless. Why good work causes it →
Markup that says what the page does not
A rating with no reviews behind it, or a price the page never shows, risks a manual action rather than a missing star. Why it happens to careful people, what an audit can and cannot tell you, and the three wrong fixes. Check yours →
The redirect your tools cannot see
A meta refresh sends the visitor onward but answers 200, so link checkers call the link fine and redirect reports never mention the hop. What that costs, why a delay above zero is worse, and the case where it is the only option your hosting gives you. Find yours in one command →
Search and cart pages in the index
Internal search results, carts and order confirmations get indexed because nothing about them looks broken — they are working exactly as built. What that costs, the one directive that fixes it, and why robots.txt is the wrong tool. Take them out →
Pagination that hides half your site
When pages two and beyond declare page one as their canonical, a crawler is told they are duplicates — and everything only reachable from them goes too. The mistake looks like good hygiene, which is why it survives. Spot it in one command →
Mobile, and what a crawl cannot see
Google indexes the mobile page, not the desktop one. Which mobile faults a crawler can genuinely prove — the viewport tag, weight, render-blocking, layout shift, numbers that will not dial — and which ones still need you to pick up a phone. What a crawl can and cannot check →
The pages that make you money
Every ranking is built from how broken a thing is, never from which page it is on — so a missing title on your pricing page sorts level with the same fault on a tag archive. How to identify yours, and why page value should break ties rather than set the order. Fix your money pages first →
Pages competing for the same search
Two of your own pages aiming at one query split the links and relevance that should back a single page, and neither ranks as well as one would. Not duplicate content — genuinely different pages, often both good, which is why nothing reports them. How to find and fix them →
Soft 404s
A missing page that answers 200 turns every mistyped URL into an indexable page. How to check it in one command, and the fix for each cause. How to fix soft 404s →
Heading structure
Four findings, not one, and the check contradicts itself on the question everyone asks. What Docket measures about headings, and where the one-H1 rule parts company with the HTML standard. Fix heading structure →
Broken outbound links
A site that refuses an automated request is not a dead site, and Docket separates the two. Which rows are rot, which are a fact about the crawl, and the one status that means the request never finished at all. How to fix broken outbound links →
Compression and caching headers
One of these is a genuine speed win and the other is quieter than it looks. Plus the case where a site that compresses perfectly is reported anyway, and the one command that tells you which you have. Fix compression and caching →
Image problems worth fixing
Docket reads image markup, never the picture, so it can tell you an image has no alt attribute and never whether the alt describes anything. Which image advice is real, and the case where reserving space correctly still leaves the finding standing. Which image SEO problems actually matter →
Redirect problems
Loops, chains, and internal links pointing at a redirect — three findings at three severities, and one thing the crawl records that cannot tell you whether a hop was permanent or temporary. How to fix redirect problems →
Navigation that needs JavaScript
Google follows a link when it is an a element with an href in the
HTML your server sent. A menu assembled by a click handler is not one. What Docket counts, and
why the empty-shell app is often not the site this catches.
How to fix navigation that needs JavaScript →
Phone links that will not dial
A tel: link can look perfect on a desktop and dial nothing when it is tapped.
The shapes that fail, which of them Docket reports and at what severity, and the one it
deliberately says nothing about.
How to fix phone links that will not dial →
Structured data errors
Invalid JSON-LD is discarded whole rather than partially read, so a page with complete markup and one trailing comma is treated like a page with none. The five ways schema breaks, and why a single-URL validator misses most of them. How to fix structured data errors →
Layout shift (CLS)
Almost always images with no width and height: the browser cannot reserve the space, so content jumps as they load. The fix, the four other causes, and why a crawler can report the risk but never the score. How to fix layout shift →
Duplicate title tags
Rarely a penalty and routinely misdiagnosed: what duplicate titles actually cost you, the character limit that does not exist, and the fix by what caused them — pagination, facets, product variants, near-identical location pages. How to fix duplicate title tags →
Missing security headers
HSTS, nosniff and Referrer-Policy, what each one actually does, and where to set them on every common host. Written as a self-audit, because this site fails two of the three checks it is describing and the reason is worth reading. How to fix missing security headers →
Auditing from an AI assistant
Docket speaks the Model Context Protocol over stdio, so an assistant can run an audit on your own Mac and read the findings back as structured data. No API key, no cloud, and the same one-time licence — the assistant is talking to the copy you own. How to set it up →
Gating a deploy on regressions
Audit production against staging and fail the build on what the deploy introduced. The case for diffing findings rather than a score: stripping every title tag from a test site left the score unchanged and registered three improvements. How to gate a deploy →
Link previews with no image
Three different faults look identical when you paste a link: no Open Graph tags, an og:image pointing at a file that no longer exists, or an image a scraper cannot reach. The dead image is the one nobody catches, because every platform caches the preview it scraped first — so the person who broke it is the last to see it broken. How to fix a broken link preview →
Title tags that fit
Search engines truncate by pixel width, not character count — which makes the usual "under sixty characters" advice wrong on any site that is not entirely English. How to write title tags that fit →
Where a bigger competitor is beatable
Authority is bought with time, and a site that has had more of it will win the queries that authority decides. Some ranking surfaces are not sold that way — and the openings are structural, which means you can find them by looking rather than by guessing at rankings nobody outside Google can see. How to find where a bigger competitor is beatable →
More coming
Further guides are being written, one per issue Docket reports. They will appear as each is written properly rather than as variations on a template.