Skip to Content
ReferenceTroubleshooting

Troubleshooting

Agent seems stuck

Symptom

Node card shows “working” but the activity timeline has no new events for >5 minutes.

Causes + fixes

  • Waiting on approval. Check the timeline for an approval_requested event. The agent blocks until you respond. Reply in the chat or approve/reject from the card.
  • Cold start. First call after a quiet period can take 30–60s to boot the container.
  • Rate limited upstream. Claude API rate limits can pause the agent mid-turn. Retries kick in automatically — give it 2–3 min.
  • Genuinely hung. Click Stop, then Resume. Reports resume from the next message.

Tool calls hang in Claude Desktop (MCP)

Symptom

do(...) call from Claude Desktop shows “in progress” for minutes with no output.

Causes + fixes

  • Agent cold start — same as above.
  • Token revoked. Re-mint from the node card; update ~/.claude.json.
  • Stream broken mid-response. Claude Desktop’s MCP client sometimes drops long streams. Cancel the tool call and retry — the agent’s server-side state is fine.
  • Wrong endpoint. Check the URL in ~/.claude.json — prod vs localhost.

Skill not being picked up

Symptom

You wrote a custom skill markdown at data/knowledge/<workspace>/skills/<slug>.md and the agent doesn’t use it when you’d expect.

Causes + fixes

  • status: draft — drafts aren’t auto-resolved. Promote to status: complete.
  • Tags mismatch. The skill-lookup step ranks by tag overlap with the user’s intent. If your skill’s tags don’t overlap with your phrasing, the match score is low. Add more tags.
  • Summary too vague. The summary is weighted heavily. Make it specific (“post a message to X with attachments, capture URL”) not abstract (“handles social posting”).
  • Invoke explicitly. You can always say “use the post-to-x skill” — explicit slug invocation bypasses the auto-resolver.

”Node not found” when calling from MCP

Symptom

do(...) returns 404 Node not found.

Causes + fixes

  • Node was deleted. Tokens are bound to a specific node. If the node was removed from the chart, the token is dead. Re-mint from a current node.
  • Wrong URL encoding. Make sure Claude Desktop isn’t mangling the role_id in the path. The default mcp-remote config handles this correctly — don’t manually URL-encode.

Webhooks (channels) silently failing

Symptom

Slack/Discord/Email channel connected, but messages sent to it aren’t arriving at the node.

Causes + fixes

  • Channel disabled. Check Workspace → Settings → Channels — ensure the channel is toggled on for this node.
  • Scope mismatch. Slack/Discord bots only respond in channels where they’re invited + the node has permission. @ the bot explicitly to test.
  • Email forwarding. If using Gmail via OAuth, check the filter rules on the Gmail side — Google sometimes auto-applies filters that archive messages before Direktor sees them.

Workspace runtime cap hit

Symptom

All nodes in a workspace freeze with a message: “Monthly runtime cap reached.”

Causes + fixes

  • Upgrade the plan for higher limits.
  • Buy overage at Workspace → Settings → Billing → Buy Runtime.
  • Wait for cycle rollover (1st of the month).
  • Reduce runtime by tightening skill workbooks — many skills have max_runtime_s hints you can lower.

I need to restore a deleted node

Symptom

You deleted a node and want its history back.

Cause + fix

The node’s history is preserved in data/archived/<workspace>/<role_id>/ on the backend for 30 days. Contact support with the workspace ID + role_id to restore; after 30 days, the data is purged per the privacy policy .

Still stuck?

Email support@direktor.tech with:

  • Workspace ID.
  • Role ID (if the issue is specific to a node).
  • A short description of what you expected vs what happened.
  • Relevant timestamps (so we can match against server logs).

Most issues resolve the same business day.

Last updated on
GlossarySkills Catalog