Troubleshooting

Common issues and solutions specific to the Smart Agents Business Central extension

This page covers issues specific to the Smart Agents Business Central extension. For general Smart Agents troubleshooting, see the main troubleshooting guide.

Installation Issues

"Extension could not be published" error

Symptom: On-premises installation fails with a publishing error.

Possible causes and solutions:

Version mismatch — The extension requires BC version 25.0 or later. Check your server version:
```
Get-NAVServerInstance | Select-Object ServerInstance, Version
```

Missing dependency — Ensure all prerequisite system apps are installed:

Get-NAVAppInfo -ServerInstance BC250 | Where-Object { $_.Name -like "*System*" }

Signature validation — If the .app file was modified after download, it will fail signature checks. Re-download the file from the Smart Agents Portal and use the -SkipVerification flag only in development environments

"Schema sync failed" error

Symptom: The Sync-NAVApp command fails during installation.

Solutions:

Check for conflicting table IDs — another extension may use an overlapping object ID range

Review the event log for detailed sync errors:

Get-NAVAppInfo -ServerInstance BC250 -Name "Smart Agents" -Version 1.0.0.0 | Get-NAVAppTenantStatus

If upgrading from a previous version, ensure the data upgrade codeunit runs successfully

Extension installs but pages are missing

Symptom: The extension shows as installed but Smart Agents pages are not found in search.

Solutions:

Clear the BC client cache: press Ctrl+Shift+Delete in the browser
Sign out and sign back in to refresh the session
Verify the extension is installed for your tenant (in multi-tenant environments):
```
Get-NAVAppTenant -ServerInstance BC250 -Name "Smart Agents"
```
Check that your user has the SMART AGENTS USER permission set

Setup Wizard Issues

Setup wizard shows "Unable to save configuration"

Symptom: The final step of the Setup Wizard fails to save.

Solutions:

Verify you have the SMART AGENTS ADMIN permission set
Check that the API key is valid by testing the connection first
If using Azure Key Vault, verify the Key Vault URI and secret name are correct
Review the Business Central error log for the specific error message

Azure Key Vault connection fails

Symptom: The Setup Wizard cannot connect to Azure Key Vault.

Solutions:

Verify the Key Vault URI format: https://your-vault-name.vault.azure.net/
Confirm the secret name matches exactly (case-sensitive): SmartAgentsApiKey
Verify the Business Central service principal has Get permission for secrets in the Key Vault access policies
For on-premises, ensure the BC server can reach Azure endpoints on port 443
Check that the Azure subscription is active and the Key Vault is not soft-deleted

Connection Issues

"SSL/TLS handshake failed" (On-Premises)

Symptom: API calls fail with a TLS error on on-premises servers.

Solutions:

Ensure TLS 1.2 is enabled on the BC server. Check the registry:
```
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client
```
The Enabled value should be 1 and DisabledByDefault should be 0
Update the .NET Framework to 4.8 or later, which uses TLS 1.2 by default
If using a proxy, ensure it supports TLS 1.2 and does not perform SSL inspection that would break certificate validation

"Proxy authentication required" (On-Premises)

Symptom: API calls fail with a 407 status code.

Solutions:

Configure proxy credentials in Smart Agents settings:
- Search for "Smart Agents API Settings"
- Under Advanced > Proxy, enter the proxy URL and credentials
Alternatively, configure the BC server's system-wide proxy settings
Whitelist api.agent.net.ai in your proxy's bypass list to skip authentication for this domain

Intermittent connection drops

Symptom: The chat interface works sometimes but frequently shows connection errors.

Solutions:

Check the BC server's outbound connection stability
Contact support at support@smart.agent.net.ai for service status
Increase the connection timeout in Smart Agents API Settings > Advanced
If using a load balancer, ensure session affinity is configured for the BC server

Performance Issues

Slow agent responses

Symptom: Agent responses take more than 30 seconds.

Solutions:

Query scope — Narrow your question to reduce the amount of data scanned. Add date ranges, filters, or specific record identifiers
Model tier — Higher-capability tiers (Expert, Premium) may take longer than Fast or Smart. Check which model tier the agent is using
Network latency — For on-premises, check the round-trip time to api.agent.net.ai:
```
Test-NetConnection -ComputerName api.agent.net.ai -Port 443
```
Data volume — If your BC environment has very large tables (millions of records), consider configuring the agent's data scope to use filtered views rather than full table scans

Chat page loads slowly

Symptom: The Smart Agents Chat page takes a long time to load.

Solutions:

Clear the browser cache and cookies for the BC domain
Check if conversation history is very large — archiving old conversations can improve load times
Disable browser extensions that may interfere with BC (e.g., ad blockers)
Check the BC server performance — the chat page may be slow if the server is under heavy load

Data Issues

Agent cannot access expected data

Symptom: The agent says it cannot find data that you know exists in Business Central.

Solutions:

Permissions — Verify your BC user has read access to the relevant tables
Data scope — Check the agent's data scope to ensure the needed tables are included:
- Open the agent's configuration page
- Review the Data Scope section
Data access policies — Check if an administrative policy restricts access:
- Ask your administrator to review Smart Agents Data Access policies
Company filter — Ensure you are in the correct BC company. The agent queries data from the current company context

Agent shows stale data

Symptom: The agent's responses contain data that does not match current records.

Solutions:

Agents query data in real-time. If you see stale data, the issue is likely a caching layer:
- Clear your browser cache
- Close and reopen the chat page
If the data was recently updated by a batch job or import, the transaction may not have committed yet. Wait a moment and retry
Check if another user has the record locked (open for editing), which may affect query results

Upgrade Issues

"Data upgrade failed" during extension update

Symptom: Updating the extension fails at the data upgrade step.

Solutions:

Review the upgrade error details:

Get-NAVAppInfo -ServerInstance BC250 -Name "Smart Agents" | Get-NAVDataUpgrade

Check for conflicting schema changes from other extensions
If the upgrade cannot proceed, contact Smart Agents support with the error details. Do not uninstall the extension, as this may result in data loss

For non-production environments, you can force the upgrade:

Start-NAVAppDataUpgrade -ServerInstance BC250 -Name "Smart Agents" -Version 1.1.0.0 -Force

Getting Help

If the solutions above do not resolve your issue:

Collect the following information:
- BC version: navigate to Help > About in Business Central
- Extension version: navigate to Extension Management and find Smart Agents
- Error message text or screenshot
- Steps to reproduce the issue
- BC event log entries (for on-premises)
Contact support at support@smart.agent.net.ai with the collected information

On this page