Troubleshooting

Start with the symptom, then check the smallest boundary that can explain it.

I cannot enable or chat#

Confirm the agent has a valid published version and every required secret and variable exists in its exact placement scope. Team values do not fall back to the organization Vault. Chat also requires the agent to be enabled.

A schedule did not run#

Check that the agent is enabled, the intended version is pinned, the cron expression is valid, and the interval is at least one hour. Use Run now to separate prompt/configuration problems from timing problems.

A schedule ran but did not post#

For implicit delivery, configure a Discord Schedule channel. For explicit delivery, confirm deliverTo.bindingId points to a connected binding. Silent responses are intentionally not posted.

Discord does not respond#

Verify the Interactions Endpoint URL, public key, application ID, slash-command name, install permissions, and enabled agent state. Enable Message Content Intent for ambient history.

Telegram misses group context#

Disable privacy with BotFather, remove and re-add the bot, and trigger it with a mention, command, or reply. Ordinary messages are buffered but do not run the agent when requireMention is true.

A turn timed out#

Aleph records an explicit timeout after the application deadline. Already visible partial progress remains available for inspection, but it is not treated as a completed scheduled or channel response. Narrow the request or split it into smaller turns.

Chat shows a connection error after refresh#

Return to the conversation or reload to reconcile it with the newest stored revision. Anything already visible—including active tools and sandbox hooks—should remain present even when a live stream can no longer be resumed. Retry only if the durable turn status is failed; retrying starts a new turn.

When diagnosis is unclear, disable the agent to stop new work while preserving versions and conversations for inspection.