Erik's ToolBox Documentation
Index

Common Issues

This page covers frequently encountered problems and their solutions when working with Erik's ToolBox for Business Central. Each issue is presented with a description of the problem, its likely cause, and the recommended solution.

If you cannot find your issue listed here, refer to the Support page for information on how to get further help.

Installation Issues

"The AL Compiler is not registered"

Problem: When you attempt to compile or run AL code in ToolBox, you receive the error message "The AL Compiler is not registered."

Cause: Your ToolBox license has not been activated, or the license validation has failed. The AL Compiler component (App ID: de0ad312-13dc-48bc-9aa4-eec46e388ee0) requires a valid license to function in production environments.

Solution:

  1. Open the Register ToolBox page in Business Central.
  2. Enter your license key and activate it.
  3. Verify that the license validation succeeds against check.hougaardlicense.com.
  4. If you are working in a sandbox environment, the compiler should function without a license. Confirm that your environment is correctly identified as a sandbox.
  5. If the problem persists, check your network connectivity to ensure the license server is reachable.

Extension Installation Fails

Problem: You are unable to install the Erik's ToolBox extension in your Business Central environment. The installation process returns an error or hangs indefinitely.

Cause: This can occur due to unmet system requirements, missing dependencies, or conflicts with other installed extensions. It may also be caused by insufficient permissions on the environment.

Solution:

  1. Verify that your Business Central version meets the minimum system requirements for ToolBox version 3.0.0.0.
  2. Check that all required dependencies are installed and up to date.
  3. Ensure that you have the necessary administrative permissions to install extensions.
  4. Review the Business Central Event Log for detailed error messages related to the installation failure.
  5. If you are installing on-premises, verify that the server instance is correctly configured for extension management.
  6. Try uninstalling any previous version of ToolBox before reinstalling.

App Not Visible After Installation

Problem: After installing Erik's ToolBox, you cannot find it in the Business Central interface. The extension does not appear in search results or navigation menus.

Cause: The browser may be serving a cached version of the Business Central interface that does not include the newly installed extension. Alternatively, the extension may have installed but not published correctly.

Solution:

  1. Refresh your browser by pressing Ctrl+F5 (hard refresh) to clear the cached version of the page.
  2. Clear your browser cache entirely and log back in to Business Central.
  3. Verify the installation by navigating to Extension Management and confirming that Erik's ToolBox (App ID: fe7b0b6a-e183-4606-882d-6adff0ce9401) appears in the list with a status of "Installed."
  4. If the extension is listed but pages are not accessible, try signing out and signing back in.
  5. Confirm that your user account has been added to the ToolBox Users.

Code Execution Issues

Compilation Errors with Line Numbers

Problem: When you attempt to compile AL code in the ToolBox editor, you receive compilation errors referencing specific line numbers. Common error types include NotImplemented, Unexpected, DuplicateIdentifier, TypeMismatch, and UndeclaredIdentifier.

Cause: The AL code contains syntax errors, unsupported constructs, or references to identifiers that the ToolBox compiler cannot resolve. Each error type indicates a different category of issue in your source code.

Solution:

  1. Review the error message carefully, paying attention to the line number and error type.
  2. Navigate to the indicated line in your code and check for syntax issues.
  3. For TypeMismatch errors, verify that you are assigning compatible data types.
  4. For UndeclaredIdentifier errors, ensure that all variables are declared in the var section before use.
  5. For DuplicateIdentifier errors, check that you have not declared the same variable name twice.
  6. For Unexpected errors, look for missing semicolons, mismatched parentheses, or incorrect keywords.
  7. Use the IntelliSense feature to verify available functions and data types as you write code.

"NotImplemented" Error

Problem: You receive a "NotImplemented" error when trying to compile or run code that uses a specific AL language feature.

Cause: ToolBox supports a subset of the full AL language. Certain advanced features, constructs, or built-in methods that are available in the standard AL development environment may not be implemented in the ToolBox interpreter.

Solution:

  1. Identify the specific AL feature that triggered the error.
  2. Check the ToolBox documentation for the list of supported AL functions and language constructs.
  3. Rewrite the affected code using an alternative approach that stays within the supported feature set.
  4. If the feature is essential for your use case, contact support to request its inclusion in a future release. See the Support page for contact details.

Runtime Errors When Accessing Records

Problem: Your code compiles successfully but produces runtime errors when attempting to read, modify, or delete records from Business Central tables.

Cause: The most common causes are insufficient table permissions for the current user, attempting to access a record that does not exist, or referencing a table or field that is not available in the current environment.

Solution:

  1. Verify that the current user has the necessary permissions to access the table in question. Check the user's permission sets in Business Central.
  2. Before modifying or deleting a record, confirm that the record exists by using a FindFirst or FindSet call and checking the return value.
  3. Ensure that the table and field names in your code match the actual objects in your Business Central environment.
  4. If you are using filters, verify that the filters are correctly applied and that matching records exist.
  5. Check the Permissions page for details on configuring user access.

Code Runs but No Output

Problem: Your AL code executes without errors, but nothing appears in the console output area.

Cause: The code does not include any output statements. Unlike some development environments, ToolBox does not automatically display the result of the last expression. You must explicitly produce output.

Solution:

  1. Add message() calls to your code to produce console output. For example: message('The result is %1', myVariable);
  2. If you are iterating over records, include a message() call inside the loop to display each record's data.
  3. Verify that your code is actually reaching the output statements by adding diagnostic messages at key points in the execution flow.
  4. Check that conditional branches (if statements) are not preventing the output code from running.

Symbol Issues

IntelliSense Not Working

Problem: The code editor does not provide auto-completion suggestions, field names, or function signatures as you type.

Cause: The symbol data for your Business Central environment has not been downloaded, or the symbol cache is empty. IntelliSense relies on downloaded symbols to provide suggestions.

Solution:

  1. Navigate to the symbol management area in ToolBox.
  2. Initiate a symbol download or refresh operation.
  3. Wait for the download to complete. The first download may take several minutes depending on the number of extensions installed in your environment.
  4. After the download completes, return to the code editor and verify that IntelliSense is now functioning.
  5. If the issue persists, try clearing the symbol cache and downloading again.

Symbol Download Fails

Problem: When you attempt to download symbols, the operation fails with a network error, authentication error, or timeout.

Cause: Symbol downloads require access to the Business Central API. Failures can result from network connectivity issues, incorrect API credentials, firewall restrictions, or server-side problems.

Solution:

  1. Check your network connectivity and ensure that the Business Central API endpoint is reachable from your environment.
  2. Verify that your authentication credentials are valid and have not expired.
  3. If you are behind a corporate firewall or proxy, ensure that the required endpoints are whitelisted.
  4. Try the download again after a short wait, as the issue may be transient.
  5. Check the Business Central server status if you are on a SaaS environment.

Tables or Fields Not Appearing

Problem: Certain tables or fields that you expect to be available are not showing up in IntelliSense or are not accessible in your code.

Cause: The symbol data may be outdated and does not reflect recent changes to the Business Central environment, such as newly installed extensions or schema modifications.

Solution:

  1. Refresh the symbols by running a new symbol download. This will update the local symbol cache with the latest metadata from your environment.
  2. If you recently installed a new extension, ensure that the extension is fully published and synced before downloading symbols.
  3. Verify that the table or field you are looking for actually exists in your environment by checking the Object Inspector or the Business Central administration tools.
  4. Remember that some system tables or fields may be restricted and not available through the standard API.

AI Agent Issues

The Agent Panel Is Missing

Problem: The Interactive Code page or the SQL Workbench shows no ToolBox Agent or SQL Agent FactBox.

Cause: The FactBox is only created when a row on the AI Providers page has the ToolBox Agent toggle on at the moment the page opens.

Solution:

  1. Open ToolBox Setup and choose AI Providers.
  2. Confirm one row has ToolBox Agent turned on and has an endpoint (and, except for LM Studio, an access key).
  3. Close and reopen the Interactive Code page or the SQL Workbench. A page that was open while you changed the setup does not pick it up.
  4. If the FactBox exists but shows "We cannot activate the agent due to missing setup", the same applies: no toggled row was found when the page opened.

Reply Starts With "ERROR Happened:"

Problem: Instead of an answer, the agent panel shows a bubble beginning with ERROR Happened: followed by a technical message.

Cause: The call to the AI provider failed. The rest of the message says why.

Solution:

  1. "Allow HttpClient Requests" is turned off for this extension: enable Allow HttpClient Requests for the AL AI Services extension in Extension Management (not only for the ToolBox).
  2. <Provider> is missing an API key: enter the Access Key on the AI Providers row.
  3. AI Provider error: 401 or 403: the key is wrong, expired, or not allowed to use the model. Regenerate it and check the model name.
  4. AI Provider error: 404: the endpoint or the model/deployment name is wrong. Compare with the reference table in AI Agents Setup.
  5. AI Provider error: 400: the model rejected the request, often because it does not support tool calling. Choose a tool-capable model.
  6. Http Error: ...: the service tier cannot reach the endpoint. Check DNS, proxy, and firewall rules; for LM Studio, check that the server runs on a host the service tier can reach.
  7. After fixing the setup, reopen the page and use Resume Conversation to continue where you were.

The Agent Is Slow or Stops With a Rate-Limit Message

Problem: Replies take a long time, or a reply eventually fails with text mentioning HTTP 429 or rate limits.

Cause: The provider throttled the requests. Each tool call is a separate round trip, so a task with many lookups makes many requests in a short time. The ToolBox retries a throttled call up to ten times, ten seconds apart, before giving up.

Solution:

  1. Wait a moment and send the message again.
  2. Raise the rate limit or tier at the provider, or switch to a provider with more headroom.
  3. Start a New Conversation when the topic changes; long conversations send more data per request.

The Agent Says No Editor Is Open

Problem: The agent answers that "No ToolBox editor is open in this session" or "No SQL Workbench is open in this session".

Cause: Tools that read or change the editor need the page that hosts the agent. This happens when two copies of the page were open in one session and the one the agent is bound to was closed, or when the page state was lost.

Solution:

  1. Close all copies of the page and open it once.
  2. Send the request again. Open only one Interactive Code page per session when you use the agent.

Changes Do Not Appear in the Editor

Problem: The agent says it replaced the program or statement, but the editor still shows the old text.

Cause: The page picks up the agent's changes on a two-second poll that starts when the page opens with an active agent.

Solution:

  1. Wait a few seconds.
  2. If nothing changes, ask the agent to call its "get" tool and confirm what it sees; then close and reopen the page and resume the conversation.

Poor Quality Results

Problem: The agent writes code or statements that do not do what you asked, or keeps failing to fix an error.

Cause: The result depends on the model, the clarity of the request, and whether the agent looked at the right tables.

Solution:

  1. Use a current, capable model. The defaults are small fast models; enter a stronger model on the AI Providers row for demanding work.
  2. Be specific: name the tables or fields you know, state the expected output, and say whether the agent should run the code.
  3. Ask it to inspect first ("look at the Sales Line table before you write this").
  4. When it loops on an error, tell it what the correct behaviour is, or fix the line yourself and ask it to continue from the editor.
  5. Review generated code in the editor before you confirm a run that writes data.

License Issues

License Expired Warning

Problem: You receive a notification that your ToolBox license has expired or is about to expire.

Cause: ToolBox licenses are time-limited and must be renewed periodically. When the license expires, certain features may become restricted in production environments.

Solution:

  1. Visit hougaard.com to renew your license.
  2. After obtaining a new license key, open the Register ToolBox page in Business Central.
  3. Enter the new license key and activate it.
  4. Verify that the license status shows as active.

Cannot Validate License

Problem: The license validation process fails when you attempt to register or verify your ToolBox license.

Cause: ToolBox validates licenses by communicating with the license server at check.hougaardlicense.com. If this server is unreachable, validation will fail.

Solution:

  1. Check your network connectivity to ensure that outbound HTTPS requests can reach check.hougaardlicense.com.
  2. If your environment is behind a firewall or proxy, add check.hougaardlicense.com to your allowlist.
  3. Try the validation again after a short wait, as the issue may be temporary.
  4. If the problem persists, contact support with your license key and environment details. See the Support page.

License Works in Sandbox but Not Production

Problem: ToolBox functions correctly in your sandbox environment but fails to activate or work in the production environment.

Cause: Sandbox environments do not require a license key for ToolBox. Production environments, however, require a valid and active license key associated with the specific environment.

Solution:

  1. Ensure that you have a valid production license key. Sandbox and production environments are licensed separately.
  2. Open the Register ToolBox page in the production environment and enter your production license key.
  3. Complete the activation process and verify that the license status is active.
  4. If you need to purchase a production license, visit hougaard.com for licensing options.
  5. See the Registration page for step-by-step activation instructions.

Permission Issues

"You Do Not Have Permission" Errors

Problem: You receive a "You do not have permission" error when trying to access ToolBox features or execute code.

Cause: Your user account does not have the necessary access level in ToolBox, or you are missing required Business Central permission sets.

Solution:

  1. Contact your ToolBox administrator (a user with GodMode access) to verify your access level.
  2. Ensure that your Business Central user account has the SUPER permission set or the appropriate permission sets for the tables and operations you are trying to perform.
  3. Check the ToolBox Users to confirm that your user account is listed and has the correct access level assigned.
  4. See the Permissions page for a detailed explanation of access levels.

Cannot Add Users

Problem: You are trying to add a new user to the ToolBox Users but the option is unavailable or returns an error.

Cause: Only users with GodMode access level can manage users in ToolBox. If your account does not have GodMode access, you will not be able to add, modify, or remove users.

Solution:

  1. Verify your access level by checking the ToolBox Users or the About ToolBox page.
  2. If you do not have GodMode access, contact an administrator who does.
  3. The first user to set up ToolBox typically receives GodMode access. If no users have GodMode access, a Business Central administrator may need to update the ToolBox User table directly.

Cannot Access ToolBox

Problem: You cannot open any ToolBox pages or features. Searches for ToolBox in Business Central return no results, or you receive access denied errors.

Cause: Your user account has not been added to the ToolBox Users. Even if the extension is installed, individual users must be granted access before they can use ToolBox.

Solution:

  1. Ask a ToolBox administrator (GodMode user) to add your Business Central user account to the ToolBox Users.
  2. Once added, sign out of Business Central and sign back in.
  3. Try accessing ToolBox again through the search bar or navigation menu.
  4. If the extension is installed but no one has access, the initial setup process may need to be completed. See the Permissions page.

Performance Issues

Slow Code Execution

Problem: Your AL code takes significantly longer to execute than expected, resulting in timeouts or sluggish performance.

Cause: Inefficient code patterns, particularly unfiltered record loops, large result sets, or repeated database operations, can cause slow execution.

Solution:

  1. Add filters to your record variables before iterating to reduce the number of records processed. Use SetRange and SetFilter to narrow the result set.
  2. Avoid nested loops where possible. If you need to join data from multiple tables, consider restructuring your logic.
  3. Use CalcFields only when you need the calculated value, rather than calling it on every record in a loop.
  4. Limit the fields you access to reduce database read overhead.
  5. If you are processing a large number of records, consider breaking the operation into smaller batches.

Excel Operations Slow

Problem: Reading from or writing to Excel files through ToolBox takes an unusually long time.

Cause: Excel operations involve file I/O and cell-by-cell processing. When working with large spreadsheets containing many cells, the overhead can accumulate significantly.

Solution:

  1. Reduce the number of cells you are reading or writing. Only process the columns and rows that are necessary for your task.
  2. When writing to Excel, batch your cell operations where possible.
  3. If you are exporting large datasets, consider whether a different output format (such as a text file) might be more efficient.
  4. Ensure that you are not repeatedly opening and closing the same Excel file in a loop.

Symbol Download Takes Long

Problem: The initial symbol download process takes a very long time, sometimes several minutes.

Cause: The symbol download retrieves metadata for all objects in your Business Central environment, including those from all installed extensions. Environments with many extensions will have more metadata to download.

Solution:

  1. Be patient during the first download. The initial symbol retrieval is expected to take longer than subsequent refreshes.
  2. Ensure a stable network connection during the download process.
  3. Subsequent symbol refreshes should be faster as only changes need to be processed.
  4. If the download consistently fails or takes an unreasonable amount of time (more than 15-20 minutes), check the Support page for assistance.
  • Support -- How to get help when you cannot resolve an issue
  • Registration -- License activation and registration steps
  • Permissions -- Understanding user access levels and permissions