Skip to main content

Error Reference

What CIN MCP errors look like, what they mean, and what to do.

Error Format​

A failed tool call returns an MCP tool error whose text follows this pattern:

Error executing tool <tool_name>: <message>; retryable=<true|false>; action=<what to do>; [x-correlation-id: <id>]
PartDescription
<message>What went wrong, including the product's HTTP status and reason when a product refused the request
retryable(Optional) Whether retrying the same call can succeed
action(Optional) The suggested next step
x-correlation-id, traceparent(Optional) IDs Hyland support uses to find the request

Errors don't include tokens, secrets or document text.

Sign-in and Connection Errors​

Sign-in required or expired​

Cause: The user hasn't signed in, or the sign-in expired (after about 15 minutes).

What the user sees: The connector shows Connect, or the client says "needs you to sign in again".

Solution:

  • Claude desktop app and Cowork: Customize → Connectors → CIN MCP → Connect.
  • Claude Code: claude mcp login hyland-cin-mcp in a terminal.
  • Codex: codex mcp login hyland-cin-mcp.

Sign-in succeeds but the client still asks to sign in​

Cause: The client secret is missing or wrong. The browser shows success, but the token exchange fails.

Solution: Claude Code: claude mcp get hyland-cin-mcp must show client_secret configured; otherwise remove the server and add it again with --client-secret. For an organization connector, remove it and add it again with the correct secret.

No tenant environment​

Cannot exchange the caller's token: no tenant environment for this request

Cause: The token doesn't name a Hyland environment, usually because the connector was set up with an older scope list.

Solution:

  1. Disconnect and reconnect so the client requests the current scopes.
  2. If it continues, your administrator checks the user's environment membership (see Subscription & Roles).

Invalid redirect URI​

Cause: The client's callback address isn't registered for your OAuth client. Hyland IAM matches redirect URIs exactly.

Solution: Claude Code must use --callback-port 8080 (http://localhost:8080/callback); Codex must use port 1455. The Claude desktop app's connector uses a fixed, registered callback; if it fails, contact Hyland support.

Blocked by policy​

Cause: Your organization's policy restricts which MCP servers local tools may use.

Solution: Ask your administrator to allow the CIN MCP server URL (see Connect Claude Code), or use the organization connector.

Access Errors​

No role for the client's app​

The current user has not been assigned any roles for the app 'X' in the environment 'Y'.

Cause: The user has no role for your OAuth client's app key in that environment.

Solution: Your administrator assigns a role for that app key in the Hyland Administration Portal.

Inactive user or wrong account​

The current user is inactive.
The Environment … is not in the user's account.

Solution: Your administrator creates or unlocks the user, or adds them to the account that owns the environment.

Product not subscribed​

An active subscription was not found for the app '…'

Cause: Your environment isn't subscribed to that product. Only that product's tools fail.

Solution: Contact Hyland to add the subscription.

403 Forbidden from a product​

… HTTP 403 … verify the caller subscription and required product permission

Cause: The subscription exists, but the user has no role for that product.

Solution: Your administrator assigns the product role (see Subscription & Roles).

Input Errors​

Argument validation​

invalid document_id
agent_id must be a canonical UUID

Cause: The server checked the input before calling the product and found it malformed.

Solution: Correct the value. Agent IDs are UUIDs; Content Lake document IDs are the document's sys_id.

Product rejected the request (400)​

Content Lake returned HTTP 400: Invalid GraphQL query syntax; retryable=false; action=correct the request parameters before retrying

Solution: Read the reason and correct the input. Knowledge graphs take GraphQL queries.

Not found (404)​

Cause: The ID is wrong, or the item is in a different environment from the one the user signed in to.

Solution: Check the ID and which environment the client is signed in to.

Server errors (5xx)​

Cause: The product couldn't complete the request.

Solution: If the error says retryable=true, wait and retry. If it persists, contact Hyland support with the correlation ID.

Behavior That Looks Like an Error​

What the user seesMeaningWhat to do
"blocked": true with blockedByGuardrailA guardrail stopped the request or answerExpected. Rephrase, or change the agent's guardrails.
Knowledge Discovery answer withheld (withheldReason)The server withheld text that looked like the service's internal instructionsRephrase or start a new conversation
Knowledge Discovery HTTP 429Rate limitedWait a minute and retry
Knowledge Discovery takes 20–30 secondsAnswers are generated synchronouslyExpected
A Content Lake query returns 0 rows with a note about an unknown propertyThe filter names a property Content Lake doesn't knowCheck the name with content_lake_metadata_fields
no service-generated markdown rendition is availableThe document has no Markdown rendition to readUse content_lake_download_document

Getting Help​

Before Contacting Support​

Collect:

  • The AI client and how it was set up (organization connector, Claude Code, Codex, Agent Builder).
  • The tool name and arguments (remove anything confidential).
  • The full error text, including x-correlation-id and traceparent.
  • The time, with time zone, and your Hyland environment.

Never share a password, access token or client secret, or a screenshot that shows one.