# Troubleshooting > Use when a Cognigy agent returns empty responses, a tool call or create_ai_agent fails, a resource is not found, setup_llm fails, or you need to diagnose a Cognigy MCP problem. - Skill: `cognigy/troubleshooting` (Agent Skill) - Install (CLI): `npx skillmds@latest add cognigy/troubleshooting` - Raw SKILL.md: https://api.skillmd.com/api/skills/cognigy/troubleshooting/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Cognigy (https://skillmd.com/u/cognigy) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/cognigy/troubleshooting --- # Troubleshooting ## Agent returns empty response 1. Inspect the agent flow and tools first: - list_resources { resourceType: "tool", aiAgentId } - duplicate `toolId` values can cause failed tool execution and empty responses 2. Check LLM exists: list_resources { resourceType: "llm_model", projectId } If none: run setup_llm 3. Check agent description is not empty: get_resource { resourceType: "agent", id } 4. Check endpoint is connected: get_resource { resourceType: "endpoint", id } Verify flowId is set and URLToken exists 5. Endpoint JUST created (seconds ago)? Endpoint config propagates briefly, and a session whose FIRST message hit the stale config stays cached as broken — wait a few seconds and retry with a NEW sessionId, not the same one. 6. LLM Prompt flows: the assigned LLM must have a connection (`connectionId` set on the llm_model). A connectionless LLM fails silently — the node's default error handling is "continue" with an empty message, which looks like an empty response. ## talk_to_agent fails (any HTTP error or timeout) talk_to_agent sends through Cognigy Endpoint Test Mode (`/test/`) so test messages are not counted as billable. It **never** re-sends a failed message on the regular (billable) endpoint by itself; a failure comes back as `error` with `testMode`, `endpointUrl` and status-aware `_hints`. **Step 1, always: find out whether the message was processed.** An HTTP error does not prove it was not. A REST endpoint's Execution Finished transformer runs after the flow and can return any status (a 404 included), and a gateway timeout can hide a completed execution. Waiting or reusing the `sessionId` does not prevent a duplicate. Check: - `get_resource { resourceType: "conversation", id: "" }` for the transcript (needs the endpoint to collect conversations), or - continue the **same** `sessionId` with a neutral follow-up ("what did you just do?"), or verify the side effects of the agent's tools. Re-send the message only if it was **not** processed. **Step 2: read the status, but do not over-interpret it.** Cognigy does not document how the 600-test-messages-per-hour cap is signalled, and the trial platform answers an empty 400 for an unknown token on both the test and the regular path, so a status alone never identifies a test-mode problem. - **404** has three possible meanings: the `/test/` route does not exist (platform older than Cognigy 4.27), the URL token is unknown (the regular URL would 404 too), or a transformer returned 404 after the flow ran. Confirm route absence independently before considering billable mode: the Cognigy release is older than 4.27 (Admin Center or release notes), **and** `get_resource { resourceType: "endpoint", id, raw: true }` shows the token matches and no Execution Finished transformer is enabled. - **400** — unknown URL token, invalid payload, or a transformer-set status. Verify the endpoint (`channel: rest`, `URLToken` present) and the payload. - **401 / 403** — authorization, IP/WAF block or an endpoint restriction, which would hit the regular URL as well. Fix what `detail` names; do not read it as "quota exhausted". - **429** — throttling, either general rate limiting or the documented 600-per-hour test budget. Pause; do not switch to `testMode: false` to get around it. - **5xx / timeout / DNS** — the request may have reached the flow before failing. Not evidence that test mode is unsupported. **Step 3: `testMode: false` is a billable production message.** Use it only when the user explicitly wants one, or when all of the following hold: the original message is confirmed unprocessed, the platform is confirmed to lack test mode, and the user has accepted the billing. ## create_ai_agent failed - The tool auto-rolls back created resources on failure. Safe to retry. - "Could not find entry node": transient issue, retry immediately - Endpoint step error: check project exists and is accessible ## "Resource not found" errors - All IDs are 24-char hex strings (e.g., 507f1f77bcf86cd799439011) - UUIDs (36-char with dashes) are referenceIds — most tools need \_id, not referenceId - Use list_resources to find valid IDs ## 401 / 403 errors, or "who changed this?" - get_resource { resourceType: "user", id: "me" } returns the account the API key belongs to, plus its `roles`. Check `roles` before blaming the API for a 403. - `createdBy` / `lastChangedBy` on any resource are opaque user ids. Never assume one is the current user — compare it to the `id` from `user`/`me`. List responses omit them; read them with get_resource { ..., raw: true }. ## Finding the most recently touched resource - Sort server-side instead of paging through everything and comparing by hand: list_resources { resourceType: "project", sort: "lastChanged:desc", limit: 5 } - `sort` takes `field:direction` and works on any field the resource returns. ## Every tool call fails with the same error, but the tool list works Suspect the network path, not the platform — listing tools makes no HTTP request, so a working list plus a uniformly failing call means requests are not reaching Cognigy. - On a corporate network, set `HTTPS_PROXY` (and `NO_PROXY` for hosts to reach directly) in the MCP server `env` block. GUI clients start the engine with a minimal environment and usually do not inherit shell proxy variables. - If the proxy inspects TLS, also set `NODE_EXTRA_CA_CERTS` to the corporate root CA file, then restart the client — Node reads it only at startup. Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0`. - An error quoting an HTML body, or naming a proxy, points at the proxy rather than Cognigy; the quoted text is the proxy's own message. - "Cannot use the configured proxy ..." means the proxy setting itself is malformed or unsupported (SOCKS proxies are not supported). Requests fail instead of connecting directly, so the API key never leaves the sanctioned path; exclude the host with `NO_PROXY` if a direct connection is intended. - "Timed out ... connecting through the proxy" means the proxy accepted the connection but never completed the tunnel. Check the proxy address, or raise `COGNIGY_PROXY_CONNECT_TIMEOUT_MS` (default 30000) if it is merely slow. - `LOG_LEVEL=debug` logs the proxy actually in use at startup. ## setup_llm fails - See the llm-providers skill for valid provider and model strings - Verify the credentials (apiKey, or AWS access keys / role ARN for awsBedrock) have access to the specified model ## delete_resource fails - Verify the resource ID is a 24-char hex string (not a referenceId UUID) - Use list_resources to confirm the resource exists before deleting - Flows, projects and agents are never hard-deleted — delete_resource renames them with a DELETE_ prefix (markedForDeletion: true) so they can be deleted manually in the Cognigy UI. Agent/flow deletion deactivates referencing endpoints (reversible); a renamed project's contents stay live.