Common Errors

This page lists error messages you may encounter in Aigentic along with their causes and solutions.

Error Reference Table

Error	Cause	Solution
API key invalid	The configured API key was rejected by the provider	Update the key in Credentials from the sidebar
Model not found	The selected model is not available from the provider	Choose a different model
Rate limited	Too many requests sent to the AI provider	Wait and retry, or reduce message frequency
Connection timeout	The AI provider took too long to respond	Retry, or switch to a faster model
Channel error	A channel connection (Discord/Telegram/Slack) failed	Check bot token via Configure on the Channels page

API Key Invalid

Error: API key invalid or expired. Provider returned: 401 Unauthorized.

Cause: The stored API key is incorrect, expired, or has been revoked by the provider.

Solution:

1. Open Credentials from the sidebar.
2. Find the provider showing the error.
3. Click the rotate icon and enter a new, valid API key.
4. Save.

Common reasons for invalid keys:

• Key was regenerated in the provider dashboard (old key is now invalid)
• Account billing issues (key disabled due to unpaid balance)
• Key restrictions (IP allowlist, rate limits) configured at the provider level
• Copy/paste error (extra whitespace or missing characters)

Provider API key pages:

• Anthropic: console.anthropic.com
• OpenAI: platform.openai.com
• xAI: console.x.ai
• NVIDIA NIM: build.nvidia.com

Tip

NVIDIA NIM models may return a 403 error even with a valid API key if you have not accepted the model’s EULA. Visit build.nvidia.com, find the model, and accept the license agreement.

Model Not Found

Error: Model "[model-name]" not found.

Cause: The model specified in the agent’s configuration is not available from the provider. This can happen when:

• A model is deprecated or renamed by the provider
• The provider account does not have access to the model
• The model ID has changed

Solution:

1. On the Agents page, click the model name (with ✎ icon) on the agent card.
2. Select an available model from the dropdown.
3. Click Save.

Rate Limited

Error: Rate limited by provider. Please wait before sending more messages.

Cause: AI providers enforce rate limits on API requests. The limits depend on your account tier and the model.

Solution:

1. Wait — The error may include a retry-after duration.
2. Reduce message frequency — If running multiple agents against the same provider, stagger activity.
3. Check your provider’s rate limits and consider upgrading your tier.
4. Distribute across providers — Use different providers for different agents.

Connection Timeout

Error: Connection to provider timed out.

Cause: The AI provider did not respond within the timeout window. This can happen during provider outages, high load, or with very long requests.

Solution:

1. Retry — Transient issues often resolve on retry.
2. Check provider status:
   • status.anthropic.com
   • status.openai.com
3. Use a faster model — Smaller models respond more quickly.
4. Reduce context size — Very long conversation histories increase response time.

Channel Connection Failed

Error: Various channel-specific errors.

Common causes and solutions:

Issue	Solution
Invalid bot token	Regenerate the token and update via Configure on the Channels page
Bot not in channel/server	Add the bot to the channel or server
Missing permissions	Re-invite the bot with correct permissions
Conflicting connections	Ensure only one connection uses each bot token

See the platform-specific guides for detailed troubleshooting:

• Discord
• Telegram
• Slack

Response Cut Off

Error: Response ends abruptly mid-sentence.

Cause: The model reached its maximum token limit for the response.

Solution:

1. Ask the agent to “continue” to get the rest of the response.
2. Increase the max tokens setting for the agent if available.
3. Ask more focused questions to get shorter responses.
4. Use a model with a larger output token limit.

Skill Load Failed

Error: Failed to load skill "[skill-name]"

Cause: The skill’s code or configuration is invalid, or dependencies are missing.

Solution:

1. Check the error details for specific information.
2. Update the skill — there may be a fix available in the ClawHub catalog.
3. Reinstall the skill.
4. Detach the skill from the agent as a temporary workaround.