How to Troubleshoot Errors with Open-SEO Skills: A Complete Debugging Guide

To troubleshoot Open-SEO skill errors, inspect the error code in the TanStack React Start server logs, check if it's listed in NON_REPORTABLE_ERROR_CODES in src/shared/error-codes.ts, and verify MCP connectivity using the self-host pre-flight script before reviewing skill parameters.

Open-SEO is an open-source SEO automation platform where agents execute skills defined in plain Markdown files within the .agents/skills/ directory. When you need to troubleshoot errors with open-seo skills, understanding how failures propagate through the TanStack React Start server and the error-handling middleware is essential for rapid root-cause analysis and resolution.

Understanding the Error Architecture

Open-SEO skills are pure Markdown workflows stored in .agents/skills/*/SKILL.md files that invoke Managed Cloud Platform (MCP) functions. When a skill fails, the error bubbles up through the TanStack React Start server and is processed by a centralized error-handling system.

The error-handling middleware in src/middleware/errorHandling.ts catches every thrown error and maps it to an AppError object. This middleware utilizes shouldCaptureAppErrorCode() from src/shared/error-codes.ts to determine whether the error should be reported to PostHog analytics or treated as a client-side issue. Validation errors, for instance, are instantiated as plain Error objects with JSON-encoded messages in src/server/lib/errors.ts, then classified as non-reportable by the error-codes catalogue.

Errors originating from MCP calls—such as RATE_LIMITED or DATAFORSEO_AUTH_FAILED—propagate through the stack and are normalized to the ErrorCode enum. The system distinguishes between reportable errors (platform issues) and non-reportable errors (user input or authentication problems) using the NON_REPORTABLE_ERROR_CODES set.

Step-by-Step Troubleshooting Workflow

Follow this systematic approach to diagnose and resolve skill failures:

1. Reproduce the failure by running the skill again via its slash-command (e.g., /docs/skills/seo-audit) and noting exact arguments.

2. Inspect server logs in the browser console or Cloudflare Workers logs. The middleware logs raw errors via console.error("server.function error:", error), revealing the stack trace and error code.

3. Identify the error code by checking the normalized ErrorCode enum in src/shared/error-codes.ts. Codes like VALIDATION_ERROR or UNAUTHENTICATED indicate client-side issues.

4. Determine reportability by checking if the code exists in NON_REPORTABLE_ERROR_CODES. Non-reportable errors are expected flows that usually indicate configuration or input problems rather than platform bugs.

5. Verify MCP connectivity using the self-host pre-flight check (scripts/selfhost-preflight.ts) or the CLI (npx skills add …) to ensure endpoints are reachable.

6. Validate input data if encountering VALIDATION_ERROR. The middleware's isValidatorError function parses JSON issue lists. Cross-reference required parameters in the skill's SKILL.md front-matter.

7. Review billing status for codes like BACKLINKS_BILLING_ISSUE or AI_SEARCH_BILLING_ISSUE by querying the billing API in src/shared/billing.ts or checking the Open-SEO UI billing page.

8. Inspect the skill definition in the relevant .agents/skills/[skill-name]/SKILL.md file to confirm the slash-command matches the filename and all MCP calls are correctly specified.

9. Run unit tests using npm test or pnpm test to verify error-code logic, particularly in src/shared/error-codes.test.ts.

10. Apply the fix based on error type: re-authenticate via src/lib/auth.ts for auth errors, adjust payloads for validation errors, wait/upgrade for rate limits, or restart MCP services for connectivity issues.

Common Error Categories and Solutions

Validation Errors (VALIDATION_ERROR)

Validation failures occur when the server function validator detects missing or malformed inputs. These errors are parsed by isValidatorError in the middleware and are not captured in PostHog because they represent user-input problems. To resolve them, review the SKILL.md front-matter parameters and ensure your agent supplies data in the correct schema.

Authentication Failures (UNAUTHENTICATED, DATAFORSEO_AUTH_FAILED)

Authentication errors surface when tokens expire or credentials are missing. The authentication logic resides in src/lib/auth.ts, which includes whoami verification and token-refresh capabilities. These codes appear in NON_REPORTABLE_ERROR_CODES because they require user action to re-authenticate rather than platform fixes.

Billing and Quota Issues

Errors prefixed with *_BILLING_ISSUE (e.g., BACKLINKS_BILLING_ISSUE, AI_SEARCH_BILLING_ISSUE) or RATE_LIMITED indicate depleted credits or exceeded quotas. Check src/shared/billing.ts to verify credit balances. While these are non-reportable errors, they block skill execution until billing is resolved or rate limits reset.

MCP Connectivity Failures

When MCP utilities in src/lib/* cannot reach project-context endpoints (get_project_context, update_project_context), skills fail with connection errors. Use the self-host pre-flight script to diagnose network connectivity, environment variables, and MCP service health before executing skills.

Debugging Code Examples

Detecting Reportable Errors

Use shouldCaptureAppErrorCode to determine if an error warrants telemetry capture:

import { shouldCaptureAppErrorCode } from "@/shared/error-codes";

function handleError(error: unknown) {
  const code = (error as any)?.code as string | undefined;
  const capture = shouldCaptureAppErrorCode(code);
  console.log(`Error code ${code} is ${capture ? "" : "not "}reportable`);
}

Manual Error Logging in Skills

For custom skill implementations, manually capture errors to PostHog before transforming them for the client:

import { captureServerError } from "@/server/lib/posthog";
import { asAppError, toClientError } from "@/server/lib/errors";

async function mySkill() {
  try {
    await someMcpCall();
  } catch (e) {
    const appError = asAppError(e);
    await captureServerError(e, {
      errorCode: appError?.code ?? "INTERNAL_ERROR",
      method: "POST",
      path: "/skills/my-skill",
    });
    throw toClientError(appError ?? e);
  }
}

Running Connectivity Diagnostics

Verify MCP health before deploying skills:

npx ts-node scripts/selfhost-preflight.ts

# Prints a summary of required environment vars, connectivity, and MCP health.

Unit Testing Error Codes

Ensure new error codes follow reporting conventions:

import { shouldCaptureAppErrorCode } from "@/shared/error-codes";

test("captures new billing issue", () => {
  expect(shouldCaptureAppErrorCode("NEW_BILLING_ISSUE")).toBe(true);
});

Critical Source Files for Investigation

When troubleshooting errors with open-seo skills, reference these specific files:

• src/shared/error-codes.ts — Contains the central ErrorCode enum, NON_REPORTABLE_ERROR_CODES set, and shouldCaptureAppErrorCode() logic that determines telemetry eligibility.
• src/middleware/errorHandling.ts — The global interceptor that transforms raw errors into AppError instances, handles logging, and forwards client-friendly messages.
• src/server/lib/errors.ts — Defines the AppError class and validation error formatting used by server functions.
• src/lib/auth.ts — Houses authentication verification and token refresh logic; source of UNAUTHENTICATED errors.
• src/lib/selfhost-preflight.ts and scripts/selfhost-preflight.ts — CLI utilities to verify MCP connectivity and environment configuration.
• .agents/skills/*/SKILL.md — Skill definition files containing workflow steps, required parameters, and MCP call specifications.
• src/shared/billing.ts — Credit and quota checking logic for resolving billing-related error codes.
• src/shared/error-codes.test.ts — Unit tests ensuring the error-code whitelist and reporting logic function correctly.

Summary

• Skill errors propagate through the TanStack React Start server and are normalized by the middleware in src/middleware/errorHandling.ts.
• Error codes are classified as reportable or non-reportable in src/shared/error-codes.ts, with validation and auth errors typically excluded from analytics.
• MCP connectivity issues are diagnosed using scripts/selfhost-preflight.ts to verify network and service health.
• Input validation failures reference the SKILL.md front-matter and are parsed by isValidatorError in the middleware.
• Billing errors require checking src/shared/billing.ts or the Open-SEO UI rather than code fixes.

Frequently Asked Questions

How do I know if an Open-SEO skill error is reportable to analytics?

Check the error code against the NON_REPORTABLE_ERROR_CODES set in src/shared/error-codes.ts. If shouldCaptureAppErrorCode(code) returns false, the error is considered a client-side or expected flow issue (like VALIDATION_ERROR or UNAUTHENTICATED) and will not be sent to PostHog. Reportable errors indicate platform or infrastructure problems.

What causes VALIDATION_ERROR in Open-SEO skills?

VALIDATION_ERROR occurs when the server function validator in src/server/lib/errors.ts detects missing required fields or schema mismatches in the skill input. The middleware's isValidatorError function parses these as JSON-encoded issue lists. Review the specific skill's SKILL.md file to verify required parameters and data shapes.

Where are skill errors logged in the Open-SEO architecture?

The error-handling middleware in src/middleware/errorHandling.ts logs all errors via console.error("server.function error:", error) before classification. Reportable errors are additionally sent to PostHog via captureServerError. For local development, check the browser console or Cloudflare Workers logs; for production, monitor the PostHog dashboard for captured server errors.

How do I fix MCP connectivity issues when running skills?

Run the self-host pre-flight script (npx ts-node scripts/selfhost-preflight.ts) to verify environment variables, network connectivity, and MCP endpoint health. If the script fails, check that the MCP service is running, firewall rules permit the connection, and the DATAFORSEO_AUTH credentials are valid. Restart the MCP service and re-run the pre-flight check before retrying the skill.

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