Skip to main content

Troubleshooting and FAQ

Common issues and their fixes. For runtime issues with a running workflow or agent, also check the Workflows and Agents console pages — most surface the failure inline. For the conceptual model behind observability, see Observability.

Install and login​

Stub — populate. Top symptoms to cover:

  • diagrid login browser doesn't open / hangs (firewall, headless environments — use --device-flow)
  • Token expiry and re-auth
  • Wrong organization selected (diagrid org list / use)
  • Proxy and corporate-network setup

See the Diagrid CLI reference for the full command surface.

Connecting an app to Catalyst​

Stub — populate. Top symptoms:

  • App ID can't reach the project endpoint (TLS, DNS, allowlist)
  • API token rejected (wrong project, expired, revoked)
  • Local dev: diagrid dev run can't bind a port

See Local development for the dev-loop tools.

Workflow runtime​

Stub — populate. Top symptoms:

  • Workflow stuck in running past expected duration → check Operate workflows for stalled-step diagnostics and diagrid workflow rerun
  • Replay errors after code change → see Workflow versioning for safe-change rules
  • Workflow can't reach activity worker → App ID connectivity / autoscaling
  • State store connectivity failures → component config + secrets

Agent runtime​

Stub — populate. Top symptoms:

  • Agent loops on same tool call → tool returning non-deterministic output, see Agent patterns
  • LLM call timeouts → see API Logs for the underlying Conversation API call
  • Memory / session not persisting → durable-agent configuration check

See Operate AI agents for inspecting running agents.

Components and managed services​

Stub — populate. Top symptoms:

  • Component YAML rejected on apply (validation errors)
  • Secret resolution failures (component metadata referencing missing secret)
  • Managed service connection limits / plan caps

See the Components reference.

MCP​

Stub — populate. Top symptoms:

  • JWT validation failures on MCP server endpoint
  • Access policy denial — see MCP access policies
  • Catalog discovery returning empty list

Where to get help​

Last updated on