Troubleshooting
Common issues and how to resolve them
Quick Diagnostic Checklist
Build Errors
Build fails with "Module not found"
A required Python package is not listed in requirements.txt
Add the missing package to your requirements.txt file and rebuild the agent.
Build fails with syntax error
Invalid Python syntax in agent code
Check your code for syntax errors. The error message will include the line number.
Build times out
Large dependencies or slow network during package installation
Try removing unused dependencies. Contact support if the issue persists.
Deployment Issues
Agent stuck in "deploying" status
Deployment process is taking longer than expected
Wait a few minutes. If status doesn't change, try redeploying.
Cloud agent not connecting
Chrona Worker is not running or misconfigured
Ensure the Chrona Worker is running and properly configured with your API key.
"Worker not available" error
No worker is registered to handle this agent type
For Cloud agents: start your Chrona Worker. For Secure agents: redeploy.
Execution
Execution stuck in "pending" status
No available worker to process the task
Check that the agent is deployed and workers are healthy.
Task fails with timeout
Agent execution took longer than the configured timeout
Increase the timeout in endpoint settings or optimize your agent code.
Input validation error
Provided inputs don't match expected types or are missing required fields
Check that all required inputs are provided with correct types.
"Agent not found" error
The referenced agent/endpoint doesn't exist or isn't deployed
Verify the agent exists and is in "deployed" status.
Volt (Channel Hub)
Webhook returns 200 but user gets no reply
Missing access grant, no deployed agent, or egress error (e.g. Teams 403)
Check Channel Hub → Access for the sender identity. Confirm at least one agent is deployed. For Teams, verify Azure Bot App ID/password and see /docs/volt/teams troubleshooting.
“You don't have access to this assistant”
Sender identity not in channel grants and not a project member with access
Add a grant: WhatsApp E.164 phone, Telegram numeric ID, Teams email/AAD ID, or Instagram scoped sender ID. Or enable Allow all users (*). Changes may take ~30s.
Teams token error AADSTS700016
Single-tenant Azure Bot without tenant ID in Channel Hub
Enter Directory (tenant) ID from Azure App registration. Do not leave blank for Single Tenant bots.
Meta webhook verification fails
Verify token mismatch or callback URL not reachable
Ensure callback is /v1/webhooks/meta and verify token matches exactly in Meta and Channel Hub.
Telegram bot ignores /start
Bot commands are not processed in the pilot
Send a plain text message (e.g. "hello") after connecting.
Volt (Slack)
Slack user cannot message the bot
User does not have a channel access grant or project membership
Add the user via Volt → Channel Hub → Slack → Access (email grant), or add them as a project member. Their Slack profile email must match.
Credential validation fails
Missing bot scopes, incorrect signing secret, or Event Subscriptions URL not verified
Regenerate the manifest from Channel Hub, confirm webhook URLs in Slack Event Subscriptions, and add scopes shown in the validation report.
Slack events not arriving
Event Subscriptions disabled, incorrect Request URL, or volt-engine-service unreachable from Slack
Confirm Event Subscriptions is on, Request URLs match Channel Hub exactly, Socket Mode is off, and signing secret matches Slack app credentials.
Authentication
Token refresh fails
Refresh token has expired or been invalidated
Log out and log back in to get new tokens.
SSO login fails
SSO configuration is incorrect or certificate has expired
Check SSO settings and verify IdP configuration matches.
"Unauthorized" error on API calls
Access token is expired or invalid
Ensure you're using a valid access token. Refresh if needed.
Still Need Help?
If you're unable to resolve your issue using this guide: