Errores y recuperación en MCP

Qué es esto

Una referencia de los errores estructurados que devuelve el servidor MCP de ComStack, con el desencadenante y el paso de recuperación exacto para cada uno. Existe para que un agente pueda autocorregirse sin intervención humana: cada herramienta de escritura falla de forma explícita con un mensaje accionable en lugar de degradarse silenciosamente.

Cómo funciona

Los errores llegan como errores MCP con un código (InvalidRequest, InvalidParams) y un mensaje; varios también incluyen una carga útil data estructurada (por ejemplo, duplicate_draft_target incluye un array collisions). La validación es de una sola pasada: create-page y update-page devuelven todos los problemas a la vez, cada uno con una cadena fix. Lea la lista completa antes de volver a intentarlo.

Errores y recuperación

Validación

ValidationFailed (InvalidParams) — los metadatos o el contenido de la página no cumplieron las reglas de la plantilla. El mensaje es ValidationFailed: page does not match all requirements (N issue(s)) seguido de una línea por problema (field, problem, supported_values, valid_examples, expected_range, fix). Solución: aplique cada fix; consulte get-doc-template id='…' para ver el esquema y metadata_example. Errores frecuentes: title de 10–60 caracteres, description de 50–160, keywords como array (una cadena codificada en JSON se fuerza y el fix muestra el array correcto), y contenido que comienza con # en lugar de ##.

Identidad de página y colisiones

A page already exists at path '…' (path_exists) — la path está ocupada. Solución: use update-page con esa path o elija una nueva.

Slug '…' (language '…') is already used … (slug_in_use) — otra página ya se despliega en esa URL. Solución: use update-page en la página conflictiva o elija un slug diferente. Se permite el mismo slug en un idioma diferente.

Invalid id format — la path contenía una barra diagonal. Solución: la path es un ID de documento plano; coloque las barras en metadata.slug (slug docs/mcp → path docs-mcp).

Page not found: '…' — get-page-content / update-page recibió una path o (slug, language) que no resuelve nada. Solución: vuelva a resolver contra get-project-state; recuerde que la path rota después de una publicación.

Editor incorrecto

… is a CUSTOM page (metadata.type="custom") — update-page intentó acceder a una página personalizada. El mensaje completo: Edit it with upload-custom-page (body_source + <T key=…> markers), not update-page. update-page edits knowledge (markdown) pages only. Solución: edítela con upload-custom-page.

wrong_tool_knowledge_page — upload-custom-page intentó acceder a una página de conocimiento: '…' (slug '…') is a KNOWLEDGE (markdown) page, not a custom page. upload-custom-page would overwrite its body with opaque body_source. Solución: edítela con update-page o elija un slug diferente para la página personalizada.

Publicación

duplicate_draft_target (InvalidRequest) — dos borradores pendientes apuntan al mismo (slug, language); no se genera ningún token. El campo data.collisions[] enumera cada path de borrador en conflicto. Solución: use discard-draft con los extras (o cambie un slug) y luego vuelva a publish.

Invalid or already-used confirmation token — el token caducó (TTL de 5 min) o ya fue utilizado. Solución: llame a publish nuevamente para obtener un token nuevo.

Manifest changed since the dry run — publish-confirm detectó un cambio en el borrador o tema desde publish. Solución: vuelva a ejecutar publish y revise el nuevo manifiesto.

Autenticación, roles y salvaguardas

project_name does not match project … — el eco de project_name no coincidió (la comparación no distingue entre mayúsculas y minúsculas y se eliminan los espacios). Solución: lea el nombre exacto desde get-project-state.

Insufficient permission: this tool requires 'manager' … — su rol es inferior al mínimo de la herramienta (las herramientas de publicación y destructivas requieren manager). Solución: que un administrador realice la acción o eleve el rol.

This API key is scoped to project '…' — se utilizó una clave de servicio con un project_id diferente al que está vinculada. Solución: pase el project_id correcto o use una clave para ese proyecto.

invalid_token / invalid_api_key (401) — el token de portador o la clave API falta, caducó o es incorrecto. Solución: vuelva a autorizar (OAuth) o rote la clave.

Específico de páginas personalizadas

is_faq=true is forbidden on custom-page docs (template.forbids_is_faq=true) — el JSON-LD de FAQ es un asunto de las páginas de conocimiento. Solución: elimine is_faq o cree la FAQ como una página de conocimiento.

body_source is … above the 2 MB hard cap — el código fuente subido es demasiado grande. Solución: mueva los recursos integrados grandes fuera de body_source.

Marker extraction failed … — un marcador <T key> / data-t-key no se pudo analizar. Solución: corrija el marcador en el desplazamiento indicado y vuelva a subir. Las claves de marcador deben coincidir con /^[a-z][a-z0-9_.]*[a-z0-9]$/ (mínimo dos caracteres).

blocked href scheme (blocked_href_scheme) — body_source contiene una URL javascript:, data: o vbscript: en un atributo href/xlink:href. Estos se envían al navegador tal como se escribieron, por lo que la carga los rechaza directamente (incluidas las formas ofuscadas o codificadas como entidades). Solución: reemplace con URLs https:, mailto:, tel:, relativas o #anchor. Las URLs data: en atributos src (imágenes integradas) no se ven afectadas.

Cuándo usar esto

Al crear un agente que debe recuperarse por sí mismo de una llamada a herramienta fallida
Al buscar la recuperación precisa para un mensaje que acaba de recibir
Al realizar pruebas previas de automatización contra las reglas de validación

Relacionado

Publicación — duplicate_draft_target y el flujo de tokens en contexto
Tipos de página — explicación de las protecciones contra herramientas incorrectas
Páginas personalizadas — creación de páginas personalizadas con upload-custom-page
Seguridad — roles, project_name y el modelo de tokens
Recursos MCP — referencias de errores disponibles como recursos transformento://