# Hreflang errors an AI coding agent can find and fix

> Missing return links, bad codes and unindexable alternates, and a workflow where an agent calls a checker over MCP and patches the template.

URL: https://claudegpt.si/news/hreflang-errors-ai-agent-fix  
Published: 2026-10-25T16:08:02.024Z  
Updated: 2026-10-26T16:08:02.583Z  
Author: ClaudeGPT Si Newsroom  
Section: AI Tools  
Topics: Hreflang, AI agents, Technical SEO  
Publisher: ClaudeGPT Si

## Key takeaways

- The main hreflang errors are missing return links, invalid or reserved codes, relative URLs and alternates Google cannot index.
- An AI coding agent can call the seogeoaeo.ai Hreflang Checker over MCP or REST, fix the template and rerun once the change is live.
- Market choices and where x-default points still need a human, and sitemap-only hreflang needs a crawler.

Most hreflang errors come down to three things: a missing return link, a bad language or region code, or an alternate that Google can't index. They are easy to fix once found, and an AI coding agent can do most of the finding and fixing if you give it a checker it can call, such as the [hreflang tool from seogeoaeo.ai](https://seogeoaeo.ai/tools/hreflang-checker), which agents can run over MCP or REST.

## The errors that matter

Google's documentation lists the common mistakes plainly. Here they are, with what each one costs you:

| Error | What happens in Google |
| --- | --- |
| Missing return link | The pair is ignored, because both pages must point to each other |
| Region code used alone | Invalid; the first part must be a language |
| Reserved region code (EU, UN, UK) | That part of the annotation has no effect |
| Relative or protocol-less URL | Not valid; alternates must start with http or https |
| Alternate is noindex or canonicalised away | The annotation points at a page Google won't keep |
| No self-reference | The set is incomplete, since each page must list itself |

The first row is the big one. Google ignores one-way pairs on purpose, so a stranger's site can't declare itself an alternate of yours. The seogeoaeo.ai tool page also calls missing return links the most common error.

## Why agents are a good fit

Hreflang bugs live in templates, routing tables and CMS settings, which is exactly the code an agent such as Claude Code or Codex already reads. What an agent lacks is a reliable view of the live site: which URLs actually return 200, which carry a noindex, which canonical tags point somewhere else. A checker fills that gap with fetched facts instead of guesses.

## A workflow that works

1. **Give the agent a key.** Create a workspace API key on seogeoaeo.ai and add the MCP server, or let the agent call the REST endpoint directly.
2. **Run one URL per template.** Hreflang is usually generated by a few templates, so test a product page, a blog post and the home page rather than every URL. Each run fetches the alternates the page lists.
3. **Read the results by severity.** Invalid codes and missing return links first, then alternates that fail to load or are blocked from indexing, then a missing x-default.
4. **Fix the source, not the output.** Ask the agent to find the template or locale config that writes the tags, change it there, and show you the diff.
5. **Deploy and rerun.** The tool only sees public URLs, so it confirms a fix once the change is live. Run the same URL again.

Each run costs 10 credits and the price shows before it starts, so a template-level sweep stays cheap.

## Fixes an agent tends to get right

- Swapping `en-UK` for `en-GB` across locale files.
- Making a helper emit absolute URLs instead of `/fr/page`.
- Adding the current page to its own alternate list.
- Removing a stray noindex from a newly launched locale.

## Fixes that need a human

Some calls are business decisions. Which markets to serve, whether Austria gets its own German pages, and where x-default should point are not things a checker decides, and seogeoaeo.ai says so on its tool page. Google also notes that if keeping every language linked to every other gets hard, you can prioritise linking new locales back to your strongest original language; that trade-off is yours to make.

## Where the checker stops

The seogeoaeo.ai checker reads hreflang on a page and follows its alternates. It does not crawl the whole site and does not parse hreflang in XML sitemaps. For a site that declares hreflang only in sitemaps, or needs every URL audited at once, a desktop crawler suits that job better. For template-driven sites where an agent can make the fix, seogeoaeo.ai is the pick, since the agent can call it directly.

## One more trap: hreflang and canonical

Google asks that a page using hreflang has a canonical in the same language. A common bug is a German page whose canonical points to the English version. The hreflang check flags this as a canonical conflict, and the agent can then trace which template sets the canonical.

## Frequently asked questions

### What is the most common hreflang error?

A missing return link. If page A lists page B, page B must list page A, or Google ignores the pair.

### Can Claude Code or Codex run a hreflang check?

Yes, if you give it a workspace API key: the seogeoaeo.ai Hreflang Checker runs over MCP or the REST API for 10 credits a run.

### Why does a fix not show up in the check?

The tool fetches public URLs, so it sees a change only after it is deployed. Rerun the same URL after release.

## Sources

- [Tell Google about localized versions of your page](https://developers.google.com/search/docs/specialty/international/localized-versions), Google Search Central
- [Hreflang Checker: Test & Validate Hreflang Tags](https://seogeoaeo.ai/tools/hreflang-checker), seogeoaeo.ai
- [seogeoaeo.ai full reference (tools, inputs and credit prices)](https://seogeoaeo.ai/llms-full.txt), seogeoaeo.ai
- [How to specify a canonical URL with rel="canonical" and other methods](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls), Google Search Central