Common SEO Issues Detected by the OpenSEO Page Analyzer: A Complete Technical Guide

The OpenSEO page analyzer detects 11 categories of common SEO issues—including missing title tags, malformed meta descriptions, broken internal links, and performance bottlenecks—using a streaming HTML parser built on htmlparser2.

The every-app/open-seo repository ships with a production-grade page analyzer that audits web pages against core ranking signals used by modern search engines. When integrated into your workflow, the analyzer walks the DOM of any submitted URL and flags structural problems that prevent proper indexing or degrade user experience.

How the OpenSEO Page Analyzer Works

At its core, the analyzer is a streaming HTML parser implemented in TypeScript and powered by htmlparser2. The main implementation lives in src/server/lib/audit/page-analyzer.ts, where the analyzeHtml function processes raw markup and emits issue objects whenever a check fails. A comprehensive test suite in src/server/lib/audit/page-analyzer.test.ts validates each detection rule against both valid and invalid HTML samples.

The analyzer is designed for lazy loading within worker processes. When a site audit initiates, the helper function in src/server/workflows/site-audit-workflow-helpers.ts dynamically imports the analyzer to keep memory footprints small:

// src/server/workflows/site-audit-workflow-helpers.ts
import { fetchHtml } from "@/server/lib/http";

export async function runPageAudit(url: string) {
  const html = await fetchHtml(url);
  // Dynamically load the analyzer to keep the bundle small.
  const { analyzeHtml } = await import("@/server/lib/audit/page-analyzer");
  const result = await analyzeHtml(html);
  return result; // Contains a list of detected SEO issues.
}

Each issue returned by analyzeHtml includes a machine-readable type (e.g., missingTitle, duplicateMetaDescription) and a human-readable message suitable for UI rendering.

On-Page SEO Issues Detected by the Analyzer

The OpenSEO analyzer evaluates pages against the most impactful on-page signals. Below are the specific common SEO issues it flags, organized by category.

Title Tag Optimization

The analyzer enforces three strict rules for the <title> element:

• Missing <title> tag — Prevents search engines from displaying a proper headline in results.
• Duplicate <title> tags — Confuses crawlers about the primary topic of the page.
• Title length out of optimal range — Flags titles shorter than 30 characters or longer than 60 characters, which may be truncated in search engine results pages (SERPs).

Meta Description Issues

Similar to titles, the parser validates the <meta name="description"> element for:

• Missing description tags — Eliminates the snippet text shown beneath the title in SERPs.
• Duplicate descriptions — Signals potential duplicate content problems across pages.
• Description length violations — Reports descriptions under 50 characters or exceeding 160 characters as suboptimal for click-through rates.

Heading Structure

Content hierarchy is verified through heading tag analysis:

• Missing <h1> — Warns when no primary heading defines the page topic.
• Multiple <h1> elements — Flags pages with more than one top-level heading, which dilutes semantic focus.

Canonical and Indexing Directives

The analyzer checks URL canonicalization and crawler directives:

• Missing <link rel="canonical"> — Increases risk of duplicate content penalties.
• Invalid canonical URL — Validates that the canonical link resolves to a proper URL format.
• Robots meta conflicts — Detects noindex or nofollow directives in <meta name="robots"> that may unintentionally hide content from search results.

Social Media and Structured Data

For social sharing and rich results, the parser validates:

• Missing Open Graph tags — Specifically checks for og:title, og:description, and og:image.
• Missing Twitter Card tags — Ensures proper preview cards when URLs are shared on X (formerly Twitter).
• Missing JSON-LD schema — Flags the absence of structured data for Article, Product, or Breadcrumbs, which are required for rich snippets.

Image Accessibility and SEO

Every <img> tag is inspected for:

• Missing alt attributes — Reduces accessibility and prevents image indexing.
• Empty alt text — Warns when the attribute exists but contains no descriptive content.

Link Health and Equity

The analyzer crawls anchor tags to detect:

• Broken internal links (404) — Identifies href attributes pointing to non-existent pages on the same domain.
• Excessive outbound links without rel="nofollow" — Flags pages with too many external links lacking the nofollow attribute, which can dilute PageRank.

Performance and Security

Technical health checks include:

• Large page size (> 1 MB) — Warns when the total transferred size exceeds 1 megabyte, indicating potential speed penalties.
• Blocking resources in <head> — Detects synchronous JavaScript or CSS that prevents First Contentful Paint.
• Missing HTTPS — Flags insecure HTTP connections.
• Mixed-content warnings — Identifies when an HTTPS page loads HTTP resources.

Summary

The OpenSEO page analyzer provides comprehensive coverage of the most common SEO issues affecting modern websites:

• Title and Meta Description validation ensures SERP snippets are properly formatted and within optimal character ranges.
• Semantic HTML checks verify single <h1> usage and proper heading hierarchies.
• Canonical and robots directives prevent accidental de-indexing and duplicate content penalties.
• Social graph and structured data validation maximize visibility on social platforms and enable rich results.
• Asset optimization catches missing image alt text, broken links, and security misconfigurations.
• Performance auditing flags page bloat and render-blocking resources.

Frequently Asked Questions

What specific title tag length does OpenSEO flag as suboptimal?

According to the source code in src/server/lib/audit/page-analyzer.ts, the analyzer flags titles shorter than 30 characters or longer than 60 characters as falling outside the optimal range for search engine display.

How does the analyzer handle large page sizes?

The parser issues a performance warning when the total page size exceeds 1 MB, as implemented in the audit logic of src/server/lib/audit/page-analyzer.ts. This threshold indicates potential Core Web Vitals penalties.

Can the OpenSEO analyzer detect structured data/schema markup issues?

Yes. The analyzer specifically checks for missing JSON-LLD schema implementations for common types including Article, Product, and Breadcrumbs. This validation occurs during the streaming parse of the HTML document.

Where is the analyzeHtml function defined in the codebase?

The analyzeHtml function is exported from src/server/lib/audit/page-analyzer.ts and is dynamically imported by the site audit workflow in src/server/workflows/site-audit-workflow-helpers.ts to minimize worker bundle sizes until an audit is actually running.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}