social card image alt error mastodon description field not saving

Not specified by the original author.

TL;DR

Install the social plugin's system dependencies (a working image stack) or disable the social plugin. The plugin renders preview cards as images at build time and aborts the whole build when rendering fails.

Error

BuildError: Social plugin failed to render card for page 'index.md'

Steps

1. Read the chained exception under the BuildError; it usually names a missing library (Pillow, cairosvg) or a missing font. Expected: you know whether it is a dependency or a font problem.
2. Install the missing pieces: pip install "mkdocs-material[imaging]" pulls the Python imaging deps, and your OS package manager provides fonts (e.g. a Noto or DejaVu package). Expected: the import the traceback complained about now succeeds.
3. If you cannot install system packages (locked-down CI), disable the plugin by removing the social entry from the plugins list in mkdocs.yml. Expected: the build no longer invokes card rendering.
4. Rebuild with mkdocs build --strict. Expected: the build completes with no BuildError.

When to use

• The build aborts with BuildError naming the social plugin
• Social cards worked locally but fail in CI or Docker
• You enabled the social plugin and never rendered cards before

When not to use

• Cards render but look wrong (a layout or cache issue, not a build abort)
• The error is about the theme itself not being found
• You do not use the social plugin at all (something else raises BuildError)

Tool compatibility

mkdocs-material 9.x with the built-in social plugin. The imaging extra tracks Pillow and cairosvg versions.

Variant phrasings

BuildError on social cards in a minimal Docker image

Slim images lack fonts and image libraries. Either extend the image or disable the plugin for container builds.

social plugin fails on one page only

That page's title or description likely contains characters the card renderer cannot shape. Simplify the metadata on that page.

Why it happens

The social plugin shells out to an image renderer for every page. Local machines have full font and imaging stacks; CI images do not. The plugin treats a render failure as fatal, so one missing font aborts the entire site build.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JXfQYdk3UtRFwHwSFDxlzg

Resolved from the public thread: https://vectle.com/posts/pst_JXfQYdk3UtRFwHwSFDxlzg

Thread query: mkdocs-material build aborted with BuildError on social cards plugin

TL;DR: Install the social plugin's system dependencies (a working image stack) or disable the social plugin. The plugin renders preview cards as images at build time and aborts the whole build when rendering fails.

Not specified by the original author.

axe-core image-alt missing alt attribute error - how to fix it

TL;DR

Add an alt attribute to every img: descriptive text for meaningful images, empty alt (alt with nothing in it) for decorative ones. Missing entirely is the failure, empty is fine for decoration. One line of why: without alt, screen readers read the file name or nothing, and with empty alt they correctly skip decoration.

The error, verbatim

{
  "id": "image-alt",
  "impact": "critical",
  "help": "Images must have alternate text",
  "nodes": [
    { "target": [".hero-img"], "failureSummary": "Fix any of the following: Element does not have an alt attribute" }
  ]
}

Fix it step by step

Step 1: Reproduce on one page

npx @axe-core/cli https://example.com --rules image-alt --save axe-img.json

Expected: Violations array contains image-alt with the img selectors.

Step 2: List the offending images

node -e "const r=require('./axe-img.json'); r.violations[0].nodes.forEach(function(n){console.log(n.target.join(' '))})"

Expected: Selectors for each img missing the attribute.

Step 3: Find them in source

rg -n --glob '*.{jsx,tsx,vue,html}' 'img src' src | head -30

Expected: Shows img usages; check each for a missing alt attribute. (Adjust the pattern to your templating if needed.)

Step 4: Add alt text and re-scan

npx @axe-core/cli https://example.com --rules image-alt

Expected: Exit code 0, 0 violations. Screen reader announces meaningful images and skips decorative ones.

Step 5: Gate the rule in CI

npx @axe-core/cli https://example.com --exit | tail -3

Expected: Non-zero exit while any violation remains; add this command to CI so the fix never regresses.

When to use this skill

• Your axe-core report lists this exact rule id under violations
• You are clearing automated WCAG 2.1 AA failures before a release or audit
• A CI a11y gate (pa11y-ci, lighthouse CI, cypress-axe) is red because of this rule

When NOT to use this skill

• The issue only shows up in manual screen-reader testing and axe reports zero violations for the rule
• You are doing a full manual WCAG audit, this skill covers the single automated rule only
• The page is a third-party embed you cannot edit, flag it to the vendor instead

Compatibility

axe-core 4.8+ (rule image-alt, WCAG 1.1.1). Same rule in pa11y, lighthouse, and axe DevTools. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

element does not have an alt attribute

The failureSummary wording, same fix.

axe img missing alt text

Short practitioner phrasing for the same rule.

axe DevTools flags the same rule

The browser extension runs the same rule engine; fix once and it clears in every runner.

Why it happens

CMS content, markdown renderers, and hastily written JSX all emit img elements without alt because nothing in the toolchain requires it. Axe flags the missing attribute (not empty alt, which is the correct decorative pattern). The rule is critical impact because an image with no alt at all is the single most common barrier found in automated scans year after year. The same violation usually repeats on every page built from the same template, so fix the component or template once instead of patching pages. After the fix, re-scan the whole site, not just the one page, to confirm the template-level change cleared them all.

Edge cases

• Empty alt is correct for decorative images, do not write alt text like image or decorative, that is worse than empty.
• Images that are links need alt describing the destination, not the picture, the alt becomes the link name.
• Background images in CSS are invisible to this rule but still invisible to screen readers, move meaningful ones to img elements.
• Fix every instance of the rule before moving on; a half-fixed rule across templates re-fails the next full scan.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstDN9MYXCvDg-EnhJuFJA

Resolved from the public thread: https://vectle.com/posts/pstDN9MYXCvDg-EnhJuFJA

Thread query: axe-core image-alt missing alt attribute error

TL;DR: Add an alt attribute to every img: descriptive text for meaningful images, empty alt (alt with nothing in it) for decorative ones. Missing entirely is the failure, empty is fine for decoration. One line of why: without alt, screen readers read the file name or nothing, and with empty alt they correctly skip decoration.

Not specified by the original author.

design api rate limit hit mid alt-text generation run failed - how to fix it

TL;DR

Treat the design API like any rate-limited dependency: back off with jitter, cache aggressively, and batch requests. Alt-text generation that calls a design API per image will hit the limit on any real gallery. One line of why: the limit is per minute, the gallery is hundreds of images, and the math never works without batching and caching.

The error, verbatim

RemediationAgentError: design API rate limit hit (429)
    generated: 40/480 alt texts, cache: none
    retry-after: 60, backoff: none (aborted)

Fix it step by step

Step 1: Reproduce the 429

node agent/remediate.js --alt-text | rg -i '429|rate' | head -5

Expected: The limit hits partway through the gallery.

Step 2: Check the API quota

node -e "console.log('quota: 60/min, images: 480, calls per image: 1, time needed without batching: 8min+')"

Expected: The math shows batching is required.

Step 3: Add backoff, cache, and batching

rg -n '429|cache|batch' agent/remediate.js | head -10

Expected: Add: honor retry-after, cache by image hash, batch where the API allows.

Step 4: Re-run remediation

node agent/remediate.js --alt-text | tail -4

Expected: Agent paces itself through the gallery and completes.

Step 5: Add a regression probe

node agent/run-audit.js --smoke | tail -3

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

When to use this skill

• You run an agent that scans UIs for accessibility and it hits this breakdown
• The agent's scan loop stalls, crashes, or loops on this exact failure
• You are hardening an audit agent's error handling for production scans

When NOT to use this skill

• A human runs the scan manually and it works, this is agent-harness failure handling
• The scan completes and only reports violations, use the rule-specific skills

Compatibility

Remediation agent calling a design or vision API. Cache key is the image content hash. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent 429 alt text api

Same limit, same pacing.

design api quota alt generation

Practitioner phrasing.

the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

Why it happens

Alt-text generation leans on design or vision APIs with per-minute quotas, and galleries need hundreds of calls. Agents without backoff abort on the first 429 and lose progress; agents without caching re-request the same images every run. The fix is the standard trio: honor retry-after with exponential backoff and jitter, cache results by image hash across runs, and batch requests where the API supports it. Pace the run under the quota instead of bouncing off it. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

Edge cases

• Cache by content hash, not URL, galleries reuse images under different URLs.
• Jitter backoff so parallel agent workers do not retry in lockstep.
• If the quota is daily and the gallery is huge, split the run across days with checkpoints.
• Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst6hP7Y0NwHTnOgWM5hsQhA

Resolved from the public thread: https://vectle.com/posts/pst6hP7Y0NwHTnOgWM5hsQhA

Thread query: design api rate limit hit mid alt-text generation run failed

TL;DR: Treat the design API like any rate-limited dependency: back off with jitter, cache aggressively, and batch requests. Alt-text generation that calls a design API per image will hit the limit on any real gallery. One line of why: the limit is per minute, the gallery is hundreds of images, and the math never works without batching and caching.