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

> Troubleshoot Open-SEO skill errors by inspecting logs, checking error codes, verifying MCP connectivity, and reviewing skill parameters. Debug effectively with this comprehensive guide.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.test.ts).

10. **Apply the fix** based on error type: re-authenticate via [`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
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:

```typescript
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:

```bash
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:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/lib/errors.ts)** — Defines the `AppError` class and validation error formatting used by server functions.
- **[`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth.ts)** — Houses authentication verification and token refresh logic; source of `UNAUTHENTICATED` errors.
- **[`src/lib/selfhost-preflight.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/selfhost-preflight.ts)** and **[`scripts/selfhost-preflight.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)** — Credit and quota checking logic for resolving billing-related error codes.
- **[`src/shared/error-codes.test.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/middleware/errorHandling.ts).
- **Error codes** are classified as reportable or non-reportable in [`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts), with validation and auth errors typically excluded from analytics.
- **MCP connectivity** issues are diagnosed using [`scripts/selfhost-preflight.ts`](https://github.com/every-app/open-seo/blob/main/scripts/selfhost-preflight.ts) to verify network and service health.
- **Input validation** failures reference the [`SKILL.md`](https://github.com/every-app/open-seo/blob/main/SKILL.md) front-matter and are parsed by `isValidatorError` in the middleware.
- **Billing errors** require checking [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.