Troubleshooting common MerchantAI issues

Use this checklist when an agent cannot complete a task, a user cannot access an agent, or a connected service is not working.

The agent cannot use my chosen AI model

• Open the agent workspace and go to Settings → Providers.
• Confirm the intended provider has a configured API key.
• Check the key and account status at the AI provider.
• In Chat, select a model available to that provider.

An employee cannot access an agent

• On the main Agents page, open Users for that agent.
• Check whether the employee's email address appears in its access list.
• Add the address and select Save, if appropriate.
• Remember that store owners always have agent access.

The agent receives an API permission error

• Open the agent's Permissions dialog.
• If using Custom Permissions, inspect the scopes of the corresponding Store-Level API Account in BigCommerce.
• Make sure the token has not been revoked and that the requested operation is allowed by those scopes.
• Do not solve a permissions error by giving the agent broader access than it actually needs.

A third-party integration is not working

• Open Integrations for the affected agent.
• Check the platform's configuration and credential status.
• Confirm the credential permits the action you requested.
• Remember that a BigCommerce token does not grant access to a separate marketing, shipping, or accounting service.

Slack communication is not working

• Recheck the Slack Bot Token, App Token, Allowed Users, and Home Channel ID in Messaging.
• Confirm the intended user is allowed by your configuration.
• Review whether a Slack-labeled conversation appears in the agent's Chat history.

An automated email has not arrived

• Verify the target address is included under Allowed Recipients for Email Delivery.
• Confirm the task completed and requested outbound delivery.
• Check the recipient's spam/junk folder and your agent's scheduled job history where applicable.

A scheduled job is missing or did not run as expected

• Open Scheduled Jobs in the agent workspace.
• If the list says No scheduled jobs found, verify that the intended schedule was created.
• Select the job to review its details and runs.
• Review the scope, time, data permissions, and delivery configuration.

Still need help?

Use the Help control in MerchantAI or contact MerchantAI support. Include the agent name, an approximate time, the task you attempted, and the error message. Never send API keys or access tokens in a support message.

Related articles

• Configure AI providers and choose a model
• Restrict an agent's BigCommerce permissions
• Schedule recurring work with your agent