Troubleshooting

Previous Next

Troubleshooting

Silent failures first — this module has more than most, because two of its three surfaces are injected into someone else's HTML and a third talks to an external API.

The chat

Symptom Likely cause
The chat answers 503 "Proveedor de IA no configurado" The API key variable for the resolved provider is missing. Note the order: the provider is chosen first (HABITO_AI_PROVIDER, default openai), and only then its key is read — so setting just ANTHROPIC_API_KEY still tries OpenAI and complains about OPENAI_API_KEY.
A new key or provider has no effect The client is built once and cached for the life of the JVM. Restart the instance. Editing the variable in a running container changes nothing and warns about nothing.
The chat hangs for a long time Neither LLM client sets an HTTP timeout, so a slow provider blocks the request thread until the socket gives up. There is no cancel from the UI.
The assistant forgets what you were doing 50 messages, or 30 minutes of inactivity, whichever comes first. Reloading the page also starts a new thread: the session id lives in a JS variable, not in a cookie.
The assistant confuses two unrelated tasks The thread is still the old one. Press ↺ to drop it — that is what it is for.
A tool failed but the reply reads like a normal answer A tool error is fed back to the model as {"error": "…"}, not raised. The system prompt tells it to report the message verbatim, but the phrasing is the model's. Check the log for the tool's real exception.

Tools

Symptom Likely cause
tools/list is empty on the admin surface h1-mcp-api is not installed, or no module has an h1McpTools/ folder. This module registers five tools; if none of them shows up, the registry itself is missing.
An external MCP client sees only two tools It connected over SSE to the admin surface. The endpoint event advertises /v1/mcp/message, the public endpoint's path, which answers from the public registry. Point the client at POST /.rest/v1/mcp/admin instead.
marketing_tag is not in the list The DX Core marketing-tags module is not installed, so its workspace does not exist. The tool checks for it and hides itself rather than being listed and failing when used.
h1mcp_keywords refuses a content type Its app has no [H1] AI decoration, so the fields are not in the form. Writing them would leave values the editor never shows. Check first that the decoration's file name matches the target app's name — when it does not, it never applies and never warns.
Another tool refuses an h1mcpKeywords* field Correct: h1mcp_keywords declares them as its own, so the content type's tool names it instead of dropping the value.
add_component refuses the component It is not available in that area according to the template. The error lists what is available; list_templates is the way to ask beforehand.
A component ended up as a plain composite instead of a component It was sent inside properties rather than under areas. website rejects an object with a templateId in properties for exactly this reason — if an older payload slipped one through, it has no mgnl:component type and no availability check.
A multi-entry field lost its other entries Writing an array is a full replace, not an append. Read it with get_page, add your entry to the array, and send the whole list.
A reference field was refused A field marked "valueFormat": "path" needs the target node's full path, not its key or its uuid. list_templates reports the workspace and root path where the candidates live.
remove_property was refused The property is required by the node's template dialog, or it is a system property (jcr:, mgnl:).
reorder / move_component answered moved: false It was already in that position. If the answer also carries clamped: true and requestedPosition, the index was out of range and it went to the nearest end — reported, never silent.
An upload by sourceUrl failed Only http/https are accepted, the request times out at 30 s (10 s to connect), and the body must be under 25 MB. A non-2xx or an empty body is refused with the status in the message.
content_type delete did nothing Two-step: the first call returns a preview. Repeat with confirm: true.

Permissions and content

Symptom Likely cause
The assistant says a page does not exist, but you can see it Every tool runs in the calling session — the logged-in user for the chat, the REST user for MCP, usually anonymous for the public surface. An unreadable node is indistinguishable from a missing one. Compare the users before suspecting the code.
A listing is empty in production and fine on author Same cause on the public instance: unpublished content, or no anonymous read ACL on that workspace.
publish fails with a command error The calling user lacks activation rights. Publishing goes through Magnolia's default catalog with that session.
The public surface exposes more than intended allowedActions limits which actions run, not what they can see. Grant anonymous read only on the workspaces you mean to expose.

Languages

Symptom Likely cause
"Idioma no configurado" A locale outside the site's configured ones. Nothing is written — the check runs before the write.
A translation was accepted but the field is not translatable It would have been refused: the validator requires the field to exist and be i18n: true, walking into composites and switchables. Check you are using the field name the dialog declares.
Other languages disappeared after an update They should not: update_page, update_component and asset update snapshot the _<locale> properties before writing and restore them afterwards, except for the fields that call rewrote. If it happened, that field was in the payload.
The keyword lists are the same in every language By design: they are not i18n. One list per item, shared by all languages.

Versions and startup

Symptom Likely cause
initialize reports version 1.0.0 The JAR was built without Maven resource filtering, so h1-mcp-build.properties still has the raw placeholders and the code fell back. Typical of a run straight from an IDE; harmless, but it means the reported version is not the deployed one.
The module does not start Its descriptor requires core, rest-integration, rest-services and h1-mcp-api. Without the REST modules or the API there is nothing to expose.
Nothing at all responds under /.rest/v1/mcp The three endpoints are registered as light-module restEndpoints definitions. If the light module did not load, they do not exist — check Tools › Definitions, and remember that an invalid definition is not replaced: Magnolia keeps the previous one live.
Developers · Configuration Repository README