Troubleshooting

Start with the run transcript. Every run and every chat keeps the full transcript, and the error is usually in the last few steps.

"Authorization required" on GitHub or Slack

GitHub on an organization or enterprise install and Slack need a one-time authorization from each person. The integration is connected, but you have not authorized it yet.

1. Open Integrations and select the integration.
2. Complete the per-user authorization.
3. Run the agent again.

If the failing run belongs to a workflow that runs as a service account, the account has no personal login. Either turn on Act as me on the account, or share the integration with the account using The Helios app as the credential mode. See credential mode.

Workflows stopped running

If your organization has used all of its credits, new chats and runs are rejected before an agent starts. Triggers still fire, but every run fails immediately. Runs already in flight finish.

Top up in your organization's billing settings. Workflows resume on their next trigger. Nothing needs to be re-enabled. See pricing and credits.

A run failed after 30 minutes

Every workflow run has a 30-minute execution limit. When it is reached, the agent is stopped and the run is marked failed with a timeout error.

• Narrow the task. A prompt that reviews ten repositories is better as ten workflows, or one workflow triggered per event.
• Tell the agent to stop early when there is nothing to do.
• Split a long task into a workflow that prepares and one that finishes, with the result handed over through an integration or the Library.

Chats have no fixed limit, but a sandbox pauses after a period of inactivity. See sandboxes.

Webhook returns 401

A webhook trigger rejects a request when the signature is wrong, when the timestamp is more than 5 minutes from server time, or when the X-Helios-Signature header is missing or does not start with sha256=. The response body is generic on purpose.

Check the three usual causes.

• The secret is signed as a UTF-8 string. Do not hex-decode it on one side.
• The body is signed exactly as sent. A proxy that reformats JSON breaks the signature.
• The clock on the sender is wrong by more than 5 minutes.

Rotating the secret takes effect at once with no overlap. Every sender gets 401 until it has the new secret. See triggers.

An integration event never fires

Only three services send events into Helios today. GitHub, Slack, and Plain. Every other integration can be called by an agent but cannot start a run. Use a schedule or a signed webhook instead.

If the service is one of the three, check the filters.

• Every GitHub event needs a repository filter. push also needs a branch filter.
• Slack events match only channels the Helios app can see. Invite the app to the channel.
• Plain needs its webhook set up by hand. Paste the URL Helios shows you into Plain's settings.

Dispatch the workflow manually with a sample payload to check that the prompt behaves before you wait for the real event.

The sandbox is paused

A sandbox stops after roughly fifteen minutes without activity. In chat, the Files panel then shows a notice that the sandbox is paused and switches to the last staged state.

Nothing is lost. Send the agent another message and a fresh sandbox starts with the same files. Staged Library edits are replayed, and any change waiting for review is still in the Changes inbox.

An agent cannot see a Library file

A file outside the run's scope reads as not found. Check that the person or service account the run belongs to can read that path, and share it as a Library path if not. See Library permissions.

A change cannot be approved

• Conflict badge. The live file changed after the agent staged its version. Ask the agent to redo the edit or discard it.
• Changed since review. The agent rewrote the file after you opened the review. Reload and review again.
• Read-only. The run was not allowed to write that folder, or you are not an editor on it.

See reviewing changes.

Still stuck

Email [email protected], or use the in-app chat. Include the run id or the chat link.