> ## Documentation Index
> Fetch the complete documentation index at: https://metamanager.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue codes

> Every issue the checker can report, what it means, and how to fix it.

The checker reports 31 distinct issues. Each carries a stable `code`, a `severity`, an `importance`, and — where a generic fix is possible — a snippet you can paste.

<Note>
  **Issue codes are a public contract.** New codes get added; existing ones are not renamed or removed without a deprecation. Branch on `code`, never on `title` or `description`, which are prose and may be reworded.
</Note>

## Severity

| Severity  | Meaning                                     |
| :-------- | :------------------------------------------ |
| `error`   | Something is broken and is costing you now. |
| `warning` | A tag that matters is missing or wrong.     |
| `tip`     | Worth improving, but nothing is broken.     |

## Importance

`required` tags every page needs, `recommended` tags most pages benefit from, `optional` refinements. Importance is about the tag; severity is about your page.

## Score weight

Only some issues move the score, and they move it by different amounts — a missing `og:image` costs more than a missing `og:locale` because one of them decides whether anybody clicks. Issues listed below as "no score impact" are advice, not deductions.

## Core HTML

### `missing_title`

**Missing title** — warning, required, costs 10 points.

This page has no \<title>. It is the single most important piece of metadata, used by search engines and as the fallback for most social previews.

```html theme={null}
<title>Your page title</title>
```

Laravel: `Meta::title('Your page title');`

### `empty_title`

**Empty title** — warning, required, no score impact.

A \<title> tag is present but contains no text.

```html theme={null}
<title>Your page title</title>
```

Laravel: `Meta::title('Your page title');`

### `title_too_long`

**Title may be truncated** — tip, recommended, no score impact.

Your title is N characters. Some platforms may truncate titles longer than about 60.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `title_too_short`

**Title is quite short** — tip, recommended, no score impact.

Your title is N characters. Titles under about 30 often leave useful space unused.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `missing_description`

**Missing description** — warning, recommended, costs 10 points.

This page has no meta description. Search engines and social platforms fall back to guessing at page content without one.

```html theme={null}
<meta name="description" content="A short summary of the page.">
```

Laravel: `Meta::description('A short summary of the page.');`

### `description_too_long`

**Description may be truncated** — tip, recommended, no score impact.

Your description is N characters. Some platforms may truncate longer descriptions.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `description_too_short`

**Description is quite short** — tip, recommended, no score impact.

Your description is N characters. Descriptions under about 70 often under-use the available space.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `missing_canonical`

**Missing canonical URL** — warning, recommended, costs 5 points.

No canonical URL is declared. Without one, duplicate or parameterised versions of this page may be treated as separate pages.

```html theme={null}
<link rel="canonical" href="https://example.com/">
```

Laravel: `Meta::canonical(url()->current());`

### `malformed_canonical`

**Malformed canonical URL** — error, required, no score impact.

The canonical URL is not an absolute http(s) URL. Canonical URLs must be absolute to be understood correctly.

```html theme={null}
<link rel="canonical" href="https://example.com/">
```

Laravel: `Meta::canonical(url()->current());`

### `duplicate_canonical`

**More than one canonical URL** — error, required, no score impact.

This page declares 0 canonical URLs. Search engines may ignore all of them.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `missing_favicon`

**Missing favicon** — warning, recommended, costs 5 points.

No favicon link was found. Browsers will fall back to /favicon.ico, which may not exist.

```html theme={null}
<link rel="icon" href="/favicon.ico" sizes="any">
```

Laravel: `Meta::favicon('/favicon.ico');`

### `missing_og_title`

**Missing og:title** — warning, recommended, costs 7 points.

Without og:title, social platforms fall back to the page title, which may not be the wording you want when shared.

```html theme={null}
<meta property="og:title" content="Example title">
```

Laravel: `Meta::openGraph()->title('Your page title');`

### `missing_og_description`

**Missing og:description** — warning, recommended, costs 7 points.

Without og:description, shared links fall back to the meta description or to nothing at all.

```html theme={null}
<meta property="og:description" content="A short summary of the page.">
```

Laravel: `Meta::openGraph()->description('A short summary of the page.');`

## Open Graph

### `missing_og_url`

**Missing og:url** — warning, recommended, costs 5 points.

og:url tells platforms the canonical address of this page, so shares of parameterised URLs consolidate correctly.

```html theme={null}
<meta property="og:url" content="https://example.com/">
```

Laravel: `Meta::canonical(url()->current());`

### `missing_og_type`

**Missing og:type** — tip, recommended, costs 4 points.

og:type describes what this page is. Most pages are "website"; articles benefit from "article".

```html theme={null}
<meta property="og:type" content="website">
```

Laravel: `Meta::type('website');`

### `missing_og_image`

**Missing og:image** — warning, recommended, costs 10 points.

Without og:image, shared links appear as plain text with no thumbnail, which markedly reduces engagement.

```html theme={null}
<meta property="og:image" content="https://example.com/og.png">
```

Laravel: `Meta::image(asset('og.png'), width: 1200, height: 630, alt: 'Description');`

### `missing_og_image_dimensions`

**Missing image dimensions** — tip, recommended, costs 4 points.

og:image:width and og:image:height let platforms reserve layout space before the image loads, avoiding a reflow in the preview.

```html theme={null}
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
```

Laravel: `Meta::image(asset('og.png'), width: 1200, height: 630);`

### `missing_og_image_alt`

**Missing og:image:alt** — tip, optional, costs 3 points.

Alt text describes the preview image to people using screen readers. Optional, but a small accessibility win.

```html theme={null}
<meta property="og:image:alt" content="Description of the image">
```

Laravel: `Meta::image(asset('og.png'), alt: 'Description of the image');`

### `missing_og_site_name`

**Missing og:site\_name** — tip, optional, costs 2 points.

og:site\_name lets platforms show your site name alongside the shared link. Optional.

```html theme={null}
<meta property="og:site_name" content="Your Site">
```

Laravel: `Meta::siteName('Your Site');`

### `missing_og_locale`

**Missing og:locale** — tip, optional, costs 2 points.

og:locale declares the language and region of this content, such as en\_US. Optional.

```html theme={null}
<meta property="og:locale" content="en_US">
```

Laravel: `Meta::locale('en_US');`

## Twitter Cards

### `missing_twitter_card`

**Missing twitter:card** — warning, recommended, costs 5 points.

Without twitter:card, X may render a smaller preview or none at all. "summary\_large\_image" gives the full-width image card.

```html theme={null}
<meta name="twitter:card" content="summary_large_image">
```

Laravel: `Meta::twitter()->card('summary_large_image');`

### `missing_twitter_title`

**Missing twitter:title** — tip, optional, costs 4 points.

X falls back to og:title when twitter:title is absent, so this only matters if you want different wording there.

```html theme={null}
<meta name="twitter:title" content="Your title">
```

Laravel: `Meta::twitter()->title('Your title');`

### `missing_twitter_description`

**Missing twitter:description** — tip, optional, costs 4 points.

X falls back to og:description when twitter:description is absent.

```html theme={null}
<meta name="twitter:description" content="A short summary.">
```

Laravel: `Meta::twitter()->description('A short summary.');`

### `missing_twitter_image`

**Missing twitter:image** — tip, optional, costs 5 points.

X falls back to og:image when twitter:image is absent.

```html theme={null}
<meta name="twitter:image" content="https://example.com/og.png">
```

Laravel: `Meta::twitter()->image(asset('og.png'));`

### `missing_twitter_site`

**Missing twitter:site** — tip, optional, costs 2 points.

twitter:site attributes the content to your account handle. Optional.

```html theme={null}
<meta name="twitter:site" content="@yourhandle">
```

Laravel: `Meta::twitter()->site('@yourhandle');`

## Images

### `image_inaccessible`

**Social image could not be loaded** — error, required, costs 2 points.

The image at null could not be loaded (unreachable). Platforms will show your link without a thumbnail.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `image_too_small`

**Social image is small** — tip, recommended, no score impact.

Your image is N by N. Platforms commonly render large cards at around 1200 by 630, and smaller images may be shown as a thumbnail instead.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `image_dimensions_mismatch`

**Declared image dimensions do not match the file** — warning, recommended, no score impact.

The page declares N by N, but the file is N by N. Platforms that trust the declared size may lay the preview out incorrectly.

```html theme={null}
<meta property="og:image:width" content="600">
<meta property="og:image:height" content="315">
```

Laravel: `Meta::image(asset('og.png'), width: 600, height: 315);`

### `og_image_too_heavy`

**Social image is heavy** — tip, recommended, no score impact.

Your social image is N KB. Nothing will refuse it — the platform limits are several megabytes — but every service that unfurls your link refetches this file, and a 1200 by 630 image usually compresses to well under 500 KB with no visible loss.

Only raised when the image was actually fetched and measured; a declared size proves nothing about the file.

<Note>No generic fix: re-exporting or recompressing is specific to your image, so `fix` is `null`.</Note>

## Consistency and URLs

### `metadata_url_not_absolute`

**Metadata URL is not absolute** — error, required, costs 3 points.

One or more metadata URLs are relative. Social platforms do not resolve relative URLs and will treat them as missing.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `insecure_metadata_url`

**Metadata URL uses http on an https page** — tip, recommended, no score impact.

This page is served over https but references metadata URLs over http. Some platforms decline to load mixed content.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>

### `metadata_inconsistent`

**Title and og:title differ** — tip, optional, costs 3 points.

Your \<title> and og:title differ. That is often deliberate, but worth confirming it is intentional.

<Note>No generic fix: this one depends on your own content, so `fix` is `null`.</Note>